innovaphone wiki - User contributions [en]

Howto:Softwarephone recommended settings

2017-01-06T10:20:01Z

Tru: /* Integration in myPBX Client */

==Applies To==
This information applies to

* innovaphone Softwarephone



==Registration Protocol==

===Problem Details===
The Softwarephone needs to setup a signaling connection to the PBX. With H323 (UDP), the signaling needs several ports and they are opened on demand for each action. Sometimes it can happen that the port opening takes too long on some Windows machines and the Softwarephone doesn't respond to any requests.

=== Conclusion ===
From v11, please use H323/TCP or H323/TLS for signaling protocol. With TCP, there is one permanent session open and this prevents any Windows Session timeouts

==QoS Settings==

===Problem Details===
Because the Softwarephone is a Realtime Communication Client, the Softwarephones network traffic must have a higher network priority than other Applications (Like all VoIP Traffic). If it is not prioritized, you can have Problems with bad Audio Quality.

=== Conclusion ===
Policy-based QoS must be configured on Windows Machines where the Softwarephone is running.

For a more detailed description, see [[Howto:Set Type of Service (ToS) DiffServ DSCP Values for innovaphone Windows Applications (SoftwarePhone, myPBX Video)]].

[[Image:Policy-basedQoS.jpg]]

==Integration in myPBX Client==

If you are using the Softwarephone with the myPBX Client, it's recommended to use the myPBX Integration where the login parameters are automatically taken from the myPBX Client.

'''This only works if Netlogon is disabled in the PBX!'''

The “Start Software Phone” flag in the myPBX configuration allows the registration and login data to be transferred automatically to the Software Phone.

[[Image:swphone-mypbx1.jpg]]

File:Swphone-mypbx1.jpg

2017-01-06T10:19:08Z

Tru:

Howto:Softwarephone recommended settings

2017-01-06T10:18:14Z

Tru:

==Applies To==
This information applies to

* innovaphone Softwarephone



==Registration Protocol==

===Problem Details===
The Softwarephone needs to setup a signaling connection to the PBX. With H323 (UDP), the signaling needs several ports and they are opened on demand for each action. Sometimes it can happen that the port opening takes too long on some Windows machines and the Softwarephone doesn't respond to any requests.

=== Conclusion ===
From v11, please use H323/TCP or H323/TLS for signaling protocol. With TCP, there is one permanent session open and this prevents any Windows Session timeouts

==QoS Settings==

===Problem Details===
Because the Softwarephone is a Realtime Communication Client, the Softwarephones network traffic must have a higher network priority than other Applications (Like all VoIP Traffic). If it is not prioritized, you can have Problems with bad Audio Quality.

=== Conclusion ===
Policy-based QoS must be configured on Windows Machines where the Softwarephone is running.

For a more detailed description, see [[Howto:Set Type of Service (ToS) DiffServ DSCP Values for innovaphone Windows Applications (SoftwarePhone, myPBX Video)]].

[[Image:Policy-basedQoS.jpg]]

==Integration in myPBX Client==

If you are using the Softwarephone with the myPBX Client, it's recommended to use the myPBX Integration where the login parameters are automatically taken from the myPBX Client.

''This only works if Netlogon is disabled in the PBX!''

The “Start Software Phone” flag in the myPBX configuration allows the registration and login data to be transferred automatically to the Software Phone.

[[Image:swphone-mypbx1.jpg]]

Howto:Faxserver with Mailclients

2016-12-21T16:37:18Z

Tru:

==Mail to Fax with Mailclients==

'''This works only for sending Mails to the Faxserver and does not work for receiving Mails from the Faxserver!'''

'''Only Mail to Fax is working directly from Clients, for Fax to Mail you need always a Mailserver!'''

These are examples howto setup the Mail-Clients for this access.

'''Example for Thunderbird:'''

[[Image:Thunderbird.jpg]]

----

'''Example for Outlook:'''

[[Image:Outlook.jpg]]

File:Orca savefile.jpg

2016-10-19T13:14:34Z

Tru:

File:Orca rows content.jpg

2016-10-19T13:14:17Z

Tru:

File:Orca addrows.jpg

2016-10-19T13:14:00Z

Tru:

File:Orca openfile.jpg

2016-10-19T13:13:37Z

Tru:

File:Download orca.jpg

2016-10-19T13:13:15Z

Tru:

Reference12r1:Concept Softwarephone

2016-10-19T13:12:00Z

Tru: /* Rollout */

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

= General =

Innovaphone SoftwarePhone is the implementation of innovaphones HW phones software as a Windows process. So all the features native to the hardwarephones are present in SoftwarePhone as well. SoftwarePhone has no UI, it is operated via myPBX or 3rd Party CTI client (ex: Estos Procall).

=System Requirements=
The innovaphone SoftwarePhone requires:
*Windows 7 or later.
*Innovaphone PBX with SoftwarePhones<v> License.

= Installation =

Prior to installing the 10.00 Version of innovaphone SoftwarePhone an eventually installed 9.00 version must be manually deinstalled. From version 10.00 on, subsequent releases can be updated without first deinstalling the older version.
When updating the installation, the previous configuration (if existing) is reused. Otherwise a default configuration is installed.

The following items are installed:

* SoftwarePhone .exe and related files (dll) in Program files (x86)\innovaphone\SoftwarePhone
* Hid.tbl (the code definitoins of supported USB headsets) in Program files (x86) \innovaphone\SoftwarePhone
* The config files „swphone_config.cfg“ and „swphone_command.cfg” in the User Roaming directory (if no previous configuration is located there, otherwise the old configuration is used, Roaming Directory Location : <drive>:\Users\<User>\AppData\Roaming\innovaphone\SoftwarePhone\)

Installation Process:

* http port 80 ist checked to be available as the SoftwarePhone ’s web configuration port. If not free, a search starting at port 10006 is executed to find a free port. The URL file, containing the configuration servers web @ is adjusted to the determined free port
* SoftwarePhone is startet.

Resetting to defaults:

*Resetting to default configuration could be done by copying the config files from the Install Directory to the Roaming Directory.

Unattended Installation of softwarephone for ALLUSERS:

*It's possible to install softwarephone for ALLUSERS by using the command:
Msiexec /i softwarephone.msi ALLUSERS=1

= Configuration =

The configuration is opened by selecting “Configuration” from the start menu. A browser connection is opend to the server running as part of SoftwarePhone and the configuration menu is displayed.

Default login is admin/swphone.

The configuration options are the same as for the hardware phones with a few specifics referring to SoftwarePhone running as a Windows process:

* User Configuration
This tab is unique in the way that it can only be accessed from the computer SoftwarePhone is running on. Here the typical End User Configurations are set: Audio, USB-headset and process operational parameters.
* Application
The Applicatons run mode and priority can be set and wheter to register with the computers name at the PBX.
* Audio
The desired audio devices can be selected.
* Audio
The Audio –Input, -Output and –Ringing device can be selected.
* USB
To use the USB headsets function buttons here the device and appropriate map are selected.

The default credentials are admin / swphone

== '''„Application, Audio and USB Configuration"''' ==

This config GUI is unique in the way that it can only be accessed (right click on the softwarephone icon) from the computer SoftwarePhone is running on. Here the typical End User Configurations are set: Audio, USB-headset and process operational parameters.

[[Image:user_config.png]]

'''Application Settings Run Mode:'''

* Manual: SoftwarePhone needs to be started manually
* Login: SoftwarePhone will be started when the user logs in (don't set this option if myPBX Launcher have option "Run Softwarephone" in the same PC).

'''Microphone:'''

The microphone selection.

'''Speaker:'''

The speaker selection

'''Ringer:'''

The Ringing device selection

'''USB Device:'''

The USB headset selction.

'''USB Map:'''

The codepage selection for the selected usb device. Here one or two choices are presented. If a selection item that refers to the selected USB Device use this. If only “generic HID Telephonie Page” is available you can try to use the headsets button (some headsets support the generic codes)

'''NOTE:''' If the headsets buttons do not work for call control, then call control is solely available through myPbx. Nevertheless the USB headset can be used as the audio-in/output device.

== '''[Tab:„Application“]''' ==

Admin mode Application configuration.

[[Image:swphone_application.jpg]]

Application Run Mode, Application Priority: see „User Configuration“

'''Register Mode:'''
* Default: Registration modes like the HW phones.

'''NOTE:''' Anonymous registration might not work in all environments, especially those that prevent multicasts. For example, when using SoftwarePhone over a vpn connection ensure that multicast forwarding is guaranteed. Also, if a virtual machine is running on the same computer it might prevent
multicasts being sent on the LAN.

* Computername:
The best way for registering SoftwarePhone at the PBX. It uses the computername as it is visible on the LAN. The computername is determined by SoftwarePhone and the appropriate parameters are set for the “Phone” modul. This configuration appears in the field “Name” under the “Phone” tab (Example for computer„LBU-VOSTRO-W7“ ):

[[Image:swphone_registration.jpg]]

== '''[Tab:"Audio”]:''' ==

Admin mode Audio configuration. Items see „User Configuration“

== '''[Tab:“USB”]:''' ==

Admin mode Audio configuration. Items see „User Configuration“

= Rollout =

Especially in larger installations it is desirable to have a mechanism for automatic configuration of the SoftwarePhones. This can be accomplished in the following way:

SoftwarePhones installation package (softwarephone .msi)can be parametrized by creating an [http://support.microsoft.com/kb/255905/en-us Orca MSI database editor] transform with the parameters:
URL and POLL. Theses parameters are entered in the “Property” table

[[Image:download_orca.jpg]]

[[Image:orca_openfile.jpg]]

[[Image:orca_addrows.jpg]]

[[Image:orca_rows_content.jpg]]

[[Image:orca_savefile.jpg]]

It is recommended that the “POLL” value be set to “1” (shortest time: 1minute).
When SoftwarePhone is installed with the transform it starts, waits 1 min (poll period) then accesses the script file specified in the “POLL” parameter and executes the commands therein.
To register SoftwarePhone with the computername at the PBX the script file should look as follows (example showing the PBX @ “192.168.178.22” with the identifier „IP800-06-25-6e” :

…
#set the PBX @ and Identifier
config change PHONE SIG /prot H323 /gk-addr 192.168.178.22 /gk-id IP800-06-25-6e

#register with computername
mod cmd APP0 app-set /op OK /reg_mode ComputerName

#reset the automatic configuration update
config add UP1 /url

#reset SoftwarePhone and apply config
reset

Another method to provide configurations to the installed SoftwarePhone s is preparing a configuration template by configuring one SoftwarePhone entity, then using the generated “swphone_commands.cfg” file in the <users roaming directory >\innovaphone\SoftwarePhone
as the template, copying it to the update location and using it in the script file:

#invoke configuration template
mod cmd UP0 cfg <update directory location>/swphone_commands.cfg

This method is particularly helpful when many USB headset of the same type are used.

= Setting QoS =
See [[Howto:Softphone recommended settings]].

= Supported USB headsets =

The following USB headsets are supported for onhook/offhook functionality:

{{FIXME|reason="Needs to be tested"}}

* innovaphone IP 10 (I)
* innovaphone IP 10 (II)
* Handset for Voip (Couple) (ZMM)
* Handset for Voip (Internet) (ZMM)
* Claritel-i750 - vp (generated)
* GN 8120 USB
* Plantronics CS50/CS60-USB Headset
* GN 9350
* GN 9335e USB port
* Jabra A330 device 2
* Jabra BIZ 2400
* Jabra LINK 320 USB
* Jabra LINK 350 USB
* Jabra LINK 360 USB *
* Jabra PRO 9460 (1041)
* Jabra PRO 94(60/70) (1042)
* Jabra GO 6470 (1003)
* Jabra GO 6470 (1004)
* Jabra PRO 930 (930-25-509-101)
* Jabra LINK 350 OC
* Jabra GO 6430 (6430-17-20-201) | Version C
* Jabra SUPREME UC (5078-230-310)
* Plantronics Savi 740
* Sennheiser VoIP USB headset
* Sennheiser DECT
* Sennheiser CEHS-CI 02
* Jabra SPEAK 410 USB Mono
* Jabra SPEAK 410 USB Stereo
* Jabra BIZ 2400 Mono USB
* Jabra BIZ 2400 USB Mono
* Jabra BIZ 2400 USB Mono (2)
* Jabra PRO 9450
* Jabra PRO 9450 (2)
* Jabra BIZ 620 Mono
* Jabra UC Voice 550 Duo(5599-829-209)
* Jabra UC Voice 550 Mono(5593-829-209)
* Jabra LINK 280(280-09)
* Jabra LINK 14201-30 (DHSG-USB Adapter)
* GN Netcom Jabra 2000 USB Duo NC EMEA
* GN2000 Stereo USB
* Plantronics - Voyager PRO UC v2 (USB/bluetooth)
* Plantronics - CALISTO P420 USB
* Plantronics - Voyager PRO UC v2 (USB/bluetooth) (2)
* Plantronics - Blackwire C320 (85619-02)
* Plantronics - Blackwire C720 (87506-02)
* Plantronics - DA45 (USB/Wired)
* Plantronics - Blackwire C620 (USB/Wired)
* Plantronics - C420 (product aa10)
* Plantronics - C420 (product aa14)
* Plantronics - C435 (P.N. 85800-05)
* Plantronics D100 (USB/Bluetooth, Savi W430, W440)

'''*''' - Reported by costumer not working the MAP keys, however was detected by the Softwarephone.

= Special headsets and behaviours =
Depending on the headset, the used firmware of the headset and special settings in the headset configuration - the standard delivered USB-HID-table inside the softphone-package will not always work.

Improvements in the hid-table concerning special headset behaviour will be delivered with new firmware/service release versions of the softwarephone.

As the "standard" hid-table may work for most of the headsets, selection of the improved table has to be done manually according to the description below:

== Activation ==
After start-up of the softwarephone, right click the softwarephone-icon in the event-tray and select "Configuration".

[[Image:Swphone_hid_adaption.png]]

At the USB-map selection, one can select the headset to be used.
In the lowermost field, the table to be used has to be selected.
If the default table does not work, the improved one named <headset>-2 can be selected.

[[Image:Swphone_hid_adaption_map.png]]

Details see below.
== Jabra 930 UC ==

* Problem: Onhook at headset only possible with two clicks.
* Fixed: to one-click-onhook
* Map to select: Jabra PRO 930-2 (930-25-509-101)
* Headset settings: [[Image:jabra930-2_settings.png]]

= Troubleshooting Connectivity Problems =

If you experience problems with softwarephone attaching to the PBX or not being able to make calls please check the following:

* '''check in the “Phone” tab whether the state is “up”'''

* '''check in the “General” tab if License is “Valid”'''

* '''Start a command window as Administrator and issue a “netstat –a –b > swphone_netstat.txt'''

In the “swphone_netstat.txt” file search for “1720”. There should be an entry like this:

'''''TCP 0.0.0.0:1720 LBU-VOSTRO-W7:0 LISTENING'''''
'''[softwarephone.exe].'''

Please search for other occurances of “'''1720'''” to ensure that no other processes listen to this port.

* '''Make a softwarephone trace to see if the packets are received by softwarephone'''

In the “Maintenance” tab “Tracing” enable “'''H.323 Signaling'''”, “'''Phone'''” and “'''All TCP/UDP Traffic'''”. Then try to make the call. In the resulting trace you should see the events like the following:

'''''0:0103:337:3 - RECV RESULT[](662 from pla(192.168.178.22:60003) type: 1)
0:0103:337:3 - PHONE_LISTEN.1 -> PHONE_REG.1 : SIG_SETUP faststart=3ac8bec cmd=PROPOSAL cdpn=400'''''

If these events are no present in the trace it could be that the firewall settings prevent some of softwarephone’s functions. This could be the Firewall.

* '''Check the firewall settings for softwarephone'''

Please open the “System Administration\Windows-Firewall\Allow Program.. Ensure that softwarephone is enabled on the required interfaces. If this doesn’t solve the problem then temporaryly disable the firewall completely and try again.
Now even with the firewall disabled there could be some other security software that causes the problem. To find out if packets to the “h323hostcall” port (1720) are filtered by the firewall you can use the commands “'''netsh wfp capture start'''” to start a trace of the test and “'''netsh wfp capture stop'''” to stop the trace. The trace is written into the file: “'''wfpdiag.cab'''” . Extract the file: “'''wfpdiag.xml'''”. In this file search for “1720”. If the packet is filtered by the firewall an entry like the following can be found:

<netEvent>
<header>
<timeStamp>2013-11-05T11:20:27.367Z</timeStamp>
<flags numItems="8">
<item>FWPM_NET_EVENT_FLAG_IP_PROTOCOL_SET</item>
<item>FWPM_NET_EVENT_FLAG_LOCAL_ADDR_SET</item>
<item>FWPM_NET_EVENT_FLAG_REMOTE_ADDR_SET</item>
<item>FWPM_NET_EVENT_FLAG_LOCAL_PORT_SET</item>
<item>FWPM_NET_EVENT_FLAG_REMOTE_PORT_SET</item>
<item>FWPM_NET_EVENT_FLAG_APP_ID_SET</item>
<item>FWPM_NET_EVENT_FLAG_USER_ID_SET</item>
<item>FWPM_NET_EVENT_FLAG_IP_VERSION_SET</item>
</flags>
<ipVersion>FWP_IP_VERSION_V4</ipVersion>
<ipProtocol>6</ipProtocol>
'''<localAddrV4>192.168.178.21</localAddrV4>'''
'''<remoteAddrV4>192.168.178.22</remoteAddrV4>'''
<localPort>'''1720'''</localPort>
<remotePort>60007</remotePort>
<scopeId>0</scopeId>
<appId>
<data> …</data>
<asString>...</asString>
</appId>
<userId>S-1-5-21-3364624427-3176291796-194291593-006</userId>
</header>
<type>FWPM_NET_EVENT_TYPE_CLASSIFY_DROP</type>
<classifyDrop>
<filterId>105267</filterId>
<layerId>44</layerId>
<reauthReason>0</reauthReason>
<originalProfile>2</originalProfile>
<currentProfile>2</currentProfile>
</classifyDrop>
</netEvent>

where the

<localAddrV4>192.168.178.21</localAddrV4>

and the

<remoteAddrV4>192.168.178.22</remoteAddrV4>

should be your computers and the PBX’s @.

* Check if the setup from the PBX is received at the local computer and what happens with it

Sometimes, Antivirus Packages can implement their own network access policy. This can result in a h323 release complete with cause “User Busy” to an incoming Setup from the PBX before any other softwarephone is reached. To see which process Sends/Receives the packets in a flow you can use the “netmon”, Microsofts free Packet tracer.

= How to obtain debug traces of softwarephone using icollect =

Included in the installation path (C:\Program Files (x86)\innovaphone\SoftwarePhone) there is a tool called '''icollect.exe'''. After we reproduce a problem we can run this tool to generate debug files that are saved in the roaming folder (C:\Users\<User>\AppData\Roaming\innovaphone) as "debug-info.zip".

If the issue it's related to an application crash please enable the "File Trace" flag at "http://localhost:10006/debug.xml" before and restart the softwarephone.

This is necessary when reporting a bug/problem with innovaphone softwarephone v11.

'''NOTE: Please when providing a crash dump captured by icollect always use the latest SR (service release) of the softwarephone. Don't send us crash dumps of older versions since this will just take more time/effort to be analyzed by our developer team.'''

=Known Issue=

=== G.711 only and G729 Optional===
The software phone does support G.711 codec only, no G.723 or G.722.
Optionally we can use G729 if G729 Channel licenses are present and available on the PBX.

===Another program is blocking the softphone===

Another program (e.g XCAPI) might be listening on tcp port 1720 as well. If you want to use both programs simultaneously you can change the signaling port of the softphone to another port like 1721.

<nowiki>http://localhost/!config add PHONE SIG /ep-addr 0.0.0.0:1721</nowiki>

If you want to find out which program is listening on which port we recommend using a little tool called TCP View. You’ll find it here:

http://technet.microsoft.com/en-us/sysinternals/bb897437.aspx

=== No license obtained from PBX if SIP Protocol it's used===

When using Innovaphone v10 softwarephone with SIP Protocol no license it's obtained from the PBX. It's necessary to use H.323 always.

=== Headset Basestation doesn't Ring ===

Often it's reported that the Basestation of Wireless Headsets doesn't Ring on incoming call, this is a feature that is missing and there exist already a Feature Request for it - [[Support:DVL-Feature_Requests#Alerting_on_Wireless_headset_base_also | Alerting on Wireless headset base also]] .

=== Windows Volume lowers automatically when receiving a call ===

The volume can be set for swphone exclusively by the Windows mixer. It appears in the mixer because it has a Audio stream Interface to the Windows Audio System, but no way adjust the volume by itself. When such an effect occurs it is best to check the Windows configuration: if it is set to Change volume for applications when certain Events occur:

[http://superuser.com/questions/74116/windows-7-lowers-applications-volume-automatically Windows 7 lowers applications' volume automatically]

=== H.323/TLS Connection not Trusted by Default ===

Please check the [[Reference11r1:Concept_H.323_over_TCP/TLS_(H.460.17)#Known_Issues|H.323/TLS Known Issues article]].

Reference10:Concept Reporting

2016-10-19T12:19:45Z

Tru: /* Report XML and CSV */

==Requirements==

It is needed to have the [[Reference10:Concept_Linux_Application_Platform|application platform]] installed and running.

===Calculation of required disk space===

An average CDR requires 2080 bytes of disk space inside the database. 
So '''one GB''' disk space is needed for ~'''516222 CDRs'''. 
One call may have one or multiple CDRs depending on the call flow, the used PBX objects and their configuration.


It is strongly recommended that you try to precalculate your required disk space and configure a suiting value under [[#Configure_scheduled_CDR_cleanup]]. 
Don't forget to configure the alarm server under [[Reference10:Concept_Linux_Application_Platform#Alarm_Server]] to receive an alarm if the disk is nearly full (10% disk space remaining).


==Installation==

Download the latest version of innovaphone reporting.

Log into the application platform, go to the Applications tag, click on [[ Reference10:Concept_Linux_Application_Platform#Upload.2FUpdate|Upload/Update]] and upload the downloaded file.
The installation will start automatically and the page will refresh every two seconds showing the installation process.
If there is no error during the installation you will see at the end "Installation was succesfull". Otherwise,
you will get "installation failed" and the reason why it went wrong.

===Hotfix===
If you have already installed the latest version of Reporting, simply download the Reporting...HotfixIncremental for your platform (VM or IPxx10) or if you have missed some hotfixes, download the Reporting...HotfixCumulative archive, which contains all hotfixes since hotfix1.
 
 
Upload this hotfix archive [[Reference10:Concept_Linux_Application_Platform#Upload.2FUpdate|here]].

==Configuration==
===Device===

====License====
It is required to have a Reporting license installed on your device. Check under [[ Reference10:General/License ]] if you already have one.

Set the Reporting flag for each PBX object, which should be reported on the objects properties page.

====CDR Gateway====
Any innovaphone device which sends [[Reference10:Concept_Call_Detail_Record_CDR_PBX|CDRs]] to the reporting application must have at least one CDR interface configured under [[ Reference10:Gateway/CDR ]]:

* Type: LOCAL-AP or REMOTE-AP/REMOTE-AP-S

If HTTP/HTTPS is selected then some other parameters must be set:

* Address: ip address of the application platform
* Port: 80 for REMOTE-AP
* Port: 443 for REMOTE-AP-S
* Method: POST/GET
* Path: ap/cdr.fcgi

The application platform is by default password protected, so you'll have to perform one of these steps: 

* configure an authenticated URL for '''ap/cdr.fcgi''' under [[ Reference10:Services/HTTP/Client ]] (recommended)
** If you configure an authenticated URL (with the linux webserver credentials), don't forget to configure port 80 or port 443 for secure transport (Remote-AP-S) like https://111.111.111.111:443/ap or http://111.111.111.111:80/ap
* configure '''ap/cdr.fcgi''' as public web path on the innovaphone application platform [[ Reference10:Concept_Linux_Application_Platform#Change_web_server_properties_and_public_access_to_the_web.2Fwebdav|Public Web Paths ]]

Configure a second CDR interface, if you use [[#Replication|Replication]].

====Enable PBX CDRs====
Enable the "Generate CDRs" flag under [[ Reference10:PBX/Config/General ]].

===innovaphone Application Platform===

If the reporting URL/user/password is not configured in your device as authenticated URL, configure '''ap/cdr.fcgi''' as public web path on the innovaphone application platform [[ Reference10:Concept_Linux_Application_Platform#Change_web_server_properties_and_public_access_to_the_web.2Fwebdav|Public Web Paths ]].

===Database===

Reporting creates the innovaphone-reporting database to store CDRs sent from any innovaphone devices (appendix 7.6 explains the database structure).
PostgreSQL is also available for other applications and any of them could create its own database.

====Password====

Reporting creates the database user '''innovaphone-reporting''' with default password '''reporting'''.
This password may be changed at the innovaphone Reporting page under Config/Database.

====Remote Access====

There are tools (PgAdmin III) that allow to connect to application databases remotely.
It is first needed to configure the IP you are connecting from under Config/Database at the innovaphone reporting page.

For the PgAdmin III it is imporant to use innovaphone-reporting as Service-DB (Wartungs-DB). Default login credentials - User: innovaphone-reporting - Password: reporting

====Delete CDRs====

You can delete CDRs for certain/all users in a certain timespan. If you enter '''%''' as object, all users are selected.

Note that PostgreSQL doesn't free the space on the disk! If you need free disk space, issue this command on the shell:
''sudo -u postgres vacuumdb -f innovaphone-reporting''
This may take some time and CDRs won't be received during this time.

====Configure scheduled CDR cleanup====

If you activate scheduled cleanup, CDRs older than the configured amount of months will be automatically deleted. 
The scheduled task is started once a day at 2 AM.

===PBX===

If you use multiple PBX devices which are not Master/Slave, you have to select, which identifier is unique for a user under Config/PBX:
* System Name (default)
* PBX Name

The selected value determines, which values are shown in the PBX dropdown box for report creation or report mail configuration.

===Replication===

You can configure a second innovaphone application platform with an installed innovaphone Reporting for replication purposes. 

* Mode:
** '''Off''': no replication
** '''Master''': the local server is the master server
** '''Standby''': the local server is the standby server, filters will be replicated from the master and can't be changed here
* Master/Standby Server: the IP address of the master or standby server
* Database password: the PostgreSQL database password of the other server (default is '''reporting''').
* Synchronisation interval: the interval in minutes (range 1-60) in which a sync is done

Now configure a second [[#CDR_Gateway|CDR Gateway]] for the standby server.

The current status can be seen here too. If the status is '''Failed''' take a look at the log file '''innovaphone Reporting Replication''' under [[ Reference10:Concept_Linux_Application_Platform#Logs|Diagnostics/Logs]] or look at the last trace output at the bottom of the page.
 
 
How replication works is described [[#Replication_2|here]].

===LDAP===

Several LDAP servers and dialing locations can be configured here. 

PBX field must correspond to a name of a PBX since PBX's names are available in CDRs. The received CDR is parsed to get the PBX name and this name will be used to find the corresponding LDAP server and dialing location needed to resolve names.

Each configured LDAP server and dialing location can be activated/deactivated with the '''active''' flag.

[[Image:ldap_update.png]]

If the country where you configure LDAP does not have Trunk/National prefix you should leave "National Prefix" and "Area Code" empty.

In the number Attributes field please do '''not''' add any additional characters to the attributes like ":P", ":D" or "@", for instance "homePhone:P, mobile:M, telephoneNumber:D". This does not work. That would be correct: "homePhone, mobile, telephoneNumber"

LDAP Internal Search flag allows reporting to perform name resolution also for internal numbers.

===Report Mails===

Automatic report generation can be configured here:

* '''time''': daytime at which the report is sent
* '''user reports''':
** Creates for each matching user a separate report
** Users are matched by '''Object (Long Name)'''
** A user report only contains calls for this user
** The email address of the user is built by its '''H323 name''' and the '''System Name''' of its PBX (h323@systemname) or determined by the E-Mail field of the user
* '''interval''':
** daily: Mail will be send daily with the automatic period "last day"
** weekly: Mail will be send weekly with the automatic period "last week"
** monthly: Mail will be send daily with the automatic period "last month"
* '''day''': the day, at which the report is sent
* '''mail adresses''': recipients of the report (comma separated)
* '''Sender E-Mail address''': sender email address, which may be present as [[ Reference10:Concept_Linux_Application_Platform#Relay_Hosts | relay host ]]
* '''compress''': compress the attachment or not
* '''sort by'''
* '''sort order'''
* '''language'''
* '''send time''': the time of a day, when the report is sent

The explanation for the other settings can be found [[ #Report_Creation | here. ]] 

[[Image:mails.png]]

===Users===

You can configure multiple users, who shall have access to reports without having access to the whole reporting configuration. 
The user can login with his user name and password on: 

http(s)://Linux-IP/apps/innovaphone-reporting/user/login.php

The admin can assign one or more base filters to the user. A base filter is explained [[ #Base_filter | here]]. 
If the user creates new reports, new own filters or report mails, he '''has''' to use one of his assigned base filters.

If you are using multiple PBX systems, the user has only access to these systems, which are configured in the base filters of the user.
If the user has no base filter with a limitation to a certain "System Name"/"PBX Name" (depends on your [[ #PBX | PBX configuration ]]),
he will have access to all systems!

[[Image:users.jpg]]

====User Login====

A logged in user can create reports, own filters and report mails based on his assigned base filters.

[[Image:Userlogin.jpg]]

===Images===

You may upload images to be used as logo or footer in pdf reports. 

Logos must be 32x32 and footer can have a maximum width of 450 pixels and a maximum height of 50 pixels. 

These images can have jpeg or png format. 

===Relay CDRs===

Relay CDRs can be stored in log files by the Reporting application. Configure a CDR gateway as already described and relay CDRs will be written to the webdav file '''/cdr/cdr.txt'''.
The file is rotated on 1 MB size. The first rotated file is uncompressed, further files will be gz compressed. Max ten files are kept. Older files will be deleted: 
* cdr.txt
* cdr.txt.1
* cdr.txt.2.gz
* cdr.txt.3.gz
* cdr.txt.4.gz
* cdr.txt.5.gz
* cdr.txt.6.gz
* cdr.txt.7.gz
* cdr.txt.8.gz
* cdr.txt.9.gz

===innovaphone-reporting web access===

You can configure a separate authentication for the innovaphone-reporting web site [[Reference10:Concept_Linux_Application_Platform#Change_application_access_credentials|here]]. 
One can just login on the reporting site with this access.

===Integration Voice recorder===

The innovaphone voice recording can be integrated and a remote control of the player is possible, see relative article.

==Filters==
===General===

Filters are set up to create reports based on certain conditions. A filter can have multiple conditions and multiple filters can be combined on report creation (combine is performed with an '''OR'''). 
A filter has a unique '''name''' with an optional '''description'''.

===Conditions===

[[Image:filter.png]]

There are five or seven condition sections depending on what is selected under '''States'''. Conditions inside same section are '''OR''' associated while different sections are '''AND''' associated.
 

(Object == Terra '''OR''' Object == Uranus) '''AND''' (PBX == sifi) '''AND''' (Number == 0049%)

====Base filter====

If you select another filter as base filter, the conditions of the base filter are implicitly '''AND''' conjuncted, when the current filter is used. 
So if the base filter defines two PBX values, e.g. "Berlin" and "Hamburg" and the current filter defines one PBX value, e.g. "Berlin", only objects of the PBX "Berlin" will be filtered: 

(pbx="Berlin") AND (pbx="Berlin" OR pbx="Hamburg")

If a user defines an own filter for his reports, he has to use a base filter, which he is allowed to use. So each filter, which he uses, will have at least one base filter condition, which the admin has defined.

You have to take care with the conditions of the current filter and the base filter,
as it is now easy to create a filter with mutually exclusive conditions, e.g. if
the filter has pbx="Berlin" and the base filter pbx="Hamburg" => no matching records.

====Anonym====

If you check this flag, a report created with this filter or with a filter, where this filter is a basefilter, will by anonymized.

====Local====

Define one ore more conditions for the local party, defined by:

* Object: the cn/PBX object name
* Number: the number
* Groups: a group of the PBX object

====Remote====

Define one or more conditions for the remote party, defined by:

* Number: the number
* Remote display name: the display name

====PBX====

Define one ore more conditions for the PBX, defined by:

* PBX: the PBX name
* Node: the node name

====States====

* No Response
* Connected
* Busy
* No Channel

====Directions====

* Incoming
* Outgoing
* Transfer: calls, which have been transferred to the current local party
* Call Forward: calls, which have been forwarded to the current local party

====Call Duration====

Time the call was connected.

This condition will be '''AND''' with the others if all '''States''' are selected. 
If Busy, No Channel or No Response is unselected, then the filter will search for Connected calls with connected time greater or smaller than '''Call Duration'''.

====Alert Duration====

Time the call was ringing independent of the status of the call afterwards.

This condition will be '''AND''' with the others if all '''States''' are selected. 
If Busy, No Channel or Connected is unselected, then the filter will search only for Not Connected Calls that were ringing more or less time than '''Alert Duration'''.

====Report times====

Define the time where calls should be counted. 
You can optionally define the weekday(s) of calls.

====Images====

* Logo: This must be 32x32 pixel image in jpeg or png format. 
* Footer: Maximum width of 450 pels and maximum height of 50 pels. Also jpeg or png format. 

====Using Patterns====

You can use these [[ #PostgreSQL_Patterns | PostgreSQL Patterns ]] for every condition.

==Report Creation==
===General===

It is possible to generate call lists for single users or more complex reports by means of filters.

===Web Interface===

Reporting application provides a web interface to generate reports.

[[Image:Report_hide.png]]

* '''PBX''': select the PBX for the report. The values of the drop down box depend on your [[#PBX | PBX configuration]]
* '''Object (Long Name)''': corresponds to the PBX Long Name assigned to a specific user (% is a special postgresql character, which matches any string)
* '''Filter''': one or multiple filters can be defined ('''OR''' joined)
* '''Group by''': the result can be grouped by Date or Object
* '''Hide last X digits''': you may replace the last digits of an external number with a '*'.
** LDAP must be configured in order to use this capability but if you want no LDAP funtionality, just unset the Active Box in LDAP.
** Actually, the pbx/phys value of a call is matched against the LDAP pbx value and if the number starts with the external line prefix.
* '''Anonym''': do not show internal names/numbers
** If anonym is set, hide last digits is set to 3, if not set
* '''Filter Info''': the report will contain information about the configured settings and filter information
* '''Displayed Duration''':
** Call Duration (Total): the total call duration, e.g. with the duration of a subsequent transfer
** Call Duration (User): just the time, the user was connected
** Billing Duration: the duration, a user must be billed for
** None of these durations contain the alert duration, which is separatly listed

[[Image:reporting_report.png | A normal report. The summary shows incoming / outgoing summaries]]

[[Image:grouped_report.png | A grouped report. Each group has an own summary]]

====Print====

Click the print icon to open a printable version of the report.

====Save====
You can save the report as '''pdf''' or as '''xml''' by using the corresponding icon. 
You can also download a report in '''csv''' format without call history. The report uses '''comma''' as delimeter character, '''"''' as text qualifier and '''PBX Object/Remote Party''' columns should be defined as Text (avoid telephone numbers to be considered as numbers by Excel). '''UTF-8''' must be used as character set. 

====Sorting====

Each sortable column has a clickable column head. This sorting will be also used when opening the printable version or saving the report as PDF.

====Icons====
The icons are explained in the [[#Call list icons|appendix]].

===Remote Interface===

See [[#Remote_Interface_2|Remote Interface Appendix]]

==Backup and Restore==

You can both manually and automatically backup the database and configuration files for Reporting under [[Reference10:Concept_Linux_Application_Platform#Backup|Administration/Backup]] in the application platform.

Configuration details for the update server can be found [[Reference10:Concept_Linux_Application_Platform#Backup|here]].

===Configuration Files===

'''saveinnovaphone-reportingcfgs''' is the command used to automatically save configuration files with the [[Reference10:Concept_Linux_Application_Platform#Command_File|Command File]].

===Data===

'''saveinnovaphone-reportingdb''' is the command to automatically backup the whole innovaphone Reporting database with the [[Reference10:Concept_Linux_Application_Platform#Command_File|Command File]].

If you restore the reporting database, you should keep in mind, that this might take several hours for a system
on a CF card, depending on the size of the restored database. The backup process itself is quite fast with a few minutes.

===Logs===

'''saveinnovaphone-reportinglogs''' to save log files with the [[Reference10:Concept_Linux_Application_Platform#Command_File|Command File]].

==Appendix==
===PostgreSQL Patterns===
For filter conditions or for the pbx object value you can use the following patterns inside a string:

* '''%''': matches any string of zero or more characters
* '''_''': matches any single character

Example:
'''Sat%''' will match all pbx objects, which start with the string '''Sat'''.

We do always perform case insensitiv searches!

===innovaphone Reporting XML===
<code type="xml">
<?xml version="1.0" encoding="utf-8"?>
<application>
<name>innovaphone Reporting</name>
<desc>Reporting software</desc>
<directory>innovaphone-reporting</directory>
<href>report.php</href>
<linux-username>innovaphone-reporting</linux-username>
<packages>
<package>php5-gd</package>
<package>php5-ldap</package>
</packages>
<database name="innovaphone-reporting" username="innovaphone-reporting"/>
<cronjobs>
<cronjob script="/etc/cron.d/reporting_replication"/>
<cronjob script="/etc/cron.d/reporting_cleanup"/>
<cronjob script="/etc/cron.d/reporting_mails"/>
</cronjobs>
<log-files>
<log title="Postgresql-8.4" no-clear="true">/var/log/postgresql/postgresql-8.4-main.log</log>
<log title="Reporting cleanup">/var/www/innovaphone/apps/innovaphone-reporting/log/reporting_cleanup.log</log>
<log title="innovaphone Reporting">/var/www/innovaphone/apps/innovaphone-reporting/log/innovaphone-reporting.log</log>
<log title="innovaphone Reporting Replication">/var/www/innovaphone/apps/innovaphone-reporting/log/reporting_replication.log</log>
</log-files>
<config-files>
<conf>/etc/postgresql/8.4/main/pg_hba.conf</conf>
<conf>/etc/postgresql/8.4/main/postgresql.conf</conf>
<conf>/home/innovaphone-reporting/reporting.conf</conf>
<conf>/home/root/ssl_cert/server.key</conf>
<conf>/home/root/ssl_cert/server.crt</conf>
<conf>/etc/cron.d/reporting_replication</conf>
<conf>/etc/cron.d/reporting_cleanup</conf>
<conf>/etc/cron.d/reporting_mails</conf>
<conf>/var/www/innovaphone/apps/innovaphone-reporting/report_images</conf>
</config-files>
<backup>
<command title="Save innovaphone Reporting configuration files" cmd="saveinnovaphone-reportingcfgs" script=""/>
<command title="Save innovaphone Reporting database" cmd="saveinnovaphone-reportingdb" script=""/>
<command title="Save innovaphone Reporting log files" cmd="saveinnovaphone-reportinglogs" script=""/>
</backup>
<restore>
<command title="Restore innovaphone Reporting configuration files" cmd="restoreinnovaphone-reportingcfgs" script="">
<action>/etc/init.d/postgresql restart</action>
<action>/etc/init.d/cron restart</action>
</command>
<command title="Restore innovaphone Reporting database" cmd="restoreinnovaphone-reportingdb" script=""/>
</restore>
<uninstall script="/usr/bin/sudo /usr/local/bin/uninstall_script.sh -f 'innovaphone-reporting.xml' -linux_user yes -linux_group yes -database yes -database_user yes -log_script '/var/www/innovaphone/log/appl_uninstall.log'">
<to-delete>
<to-del path="/usr/local/bin/reporting_cleanup.sh"/>
<to-del path="/usr/local/bin/reporting_replication.out"/>
<to-del path="/usr/local/bin/reporting_replication.sh"/>
<to-del path="/home/innovaphone-reporting/tmp"/>
</to-delete>
</uninstall>
<lighttpd-auth>1</lighttpd-auth>
<public-web-paths>
<path>mypbx</path>
<path>user</path>
</public-web-paths>
</code>

===Installed Debian Packages===

The following packages (and their dependencies) are installed with innovaphone Reporting:

* php5-gd
* php5-ldap

===Configuration Files===

pg_hba.conf is the client authentication configuration file and controls which hosts are allowed to connect, how clients
are authenticated, which PostgreSQL user names they can use and which databases they can access.

postgresql.conf is the PostgreSQL configuration file

===Data Files===

If you backup the innovaphone reporting database, you'll get a gz archiv, which contains the whole innovaphone-reporting database.

===Report XML and CSV===
The field description below applies for the '''XML''' and '''CSV''' columns!

<code type="xml">
<report>
<record>
....
<time time="1301303966" utc="1301303966">2011-03-28 11:19:26</time>
<obj>Saturn</obj>
<id>870998fee909d311b2ec009033105dc9</id>
<call>int</call>
<alert-duration seconds="0">0:00</alert-duration>
<flow>
<ev caller="ep1" ep1_number="101" ep1_name="saturn" ep1_dn="Saturn"
ep2_number="102" ep2_name="uranus" ep2_dn="Uranus" status="co" entry="true"/>
</flow>
<call-duration seconds="2">0:02</call-duration>
<billing-duration seconds="2">0:02</billing-duration>
<conn-duration seconds="2">0:02</conn-duration>
<groups>
<group>test</group>
<group>test2</group>
</groups>
<node>root</node>
<pbx>.</pbx>
<cause></cause>
<dir>o</dir>
<status>co</status>
<type/>
<remote number="102" name="uranus" dn="Uranus"/>
<callback number="456" name="abc" dn="123" time="1301305962">2011-03-28 11:52:42</callback>
</record>
....
</report>
</code>

* time: the node contains a formatted time string of the local time
** attribute '''time''' is a unix timestamp (referring to the local time stamp of the CDR)
** attribute '''utc''' is a unix timestamp (referring to the utc time stamp of the CDR)
* obj: the PBX object name (also called cn)
* id: the conference id of the call
* call: '''int''' (internal) or '''ext''' (external) call
* flow '''(XML only)''': the call flow
** ev
***ep1 (ep1_number, ep1_name, ep1_dn): the left side of the call
***ep2 (ep2_number, ep2_name, ep2_dn): the right side of the call
***caller: '''ep1''', '''ep2''' or empty, if unknown
***status: '''co''' (connected), '''al''' (alert), '''er''' (error) or '''bu''' (busy) state of the current event
***entry: '''true''' for the entry event of the local object
***type: '''cf''' (call forward), '''ct''' (call transfer)
* Original Called '''(CSV only)''': In case of Call flow; The original called device
* Diverting '''(CSV only)''': In case of Call flow; The diverting device
* Transferring '''(CSV only)''': In case of Call flow; The transferring device
* groups '''(XML only)''': the groups of the PBX object
* node: the node of the PBX object
* pbx: the pbx of the PBX object
* cause: the decimal disconnect reason of the call (see [[Reference:ISDN_Cause_Codes]])
* remote:
** outgoing calls -> dialed endpoint
** incoming calls -> first ep2 above entry event or entry event if this is the first one
** incoming calls with incoming transfer after entry event -> transfer target
* status:
** outgoing calls -> best found status in call flow
** incoming calls -> status of entry event
* type: the type of the entry event or, if not set, the type of the next event, if given
** empty: direct call
** '''ct''': call transfer
** '''cf''': call forward
** '''cct''': call transfer with consultation
** '''pu''': call pickup
* dir: o (outgoing) if the first event is the entry event and the caller is ep1
* dir: i (incoming) if not o
* alert-duration: alert time
*Billing Duration: the duration, a user must be billed for
** outgoing call -> duration from the first event until the last event in the flow
** incoming call -> duration from the first transfer/forward event until the last event in the flow
* call-duration/Call Duration (Total): duration of the whole call, e.g. with the duration of a subsequent transfer
* conn-duration/Call Duration (User): just the time, the user was connected. Duration from the entry event until the event, where the local endpoint isn't connected any more
* callback: '''name''', '''number''', '''dn''' and '''time''' if this call has been callbacked using mypbx (time referrs to the UTC time of the callback)
* Further Registration: If more than one devices is registered to the same object, each device creates a CDR. This field identifies the additional CDRs for the same call
* Object Info '''(CSV only)''': combination of object names and number
* Date '''(CSV only)''': extracted date only from the time_string
* Time_2 '''(CSV only)''': extracted time only from the time_string

===Database Structure===

====cdrs====
Each received cdr-xml is formed by a cdr tag and an undefined number of event and group tags.
(Refer to: [[Reference10:Concept_Call_Detail_Record_CDR_PBX|CDR]])

This section is composed by four tables: cdrs, events, groups and cdr_properties.
The first three tables contain the corresponding fields to store the information contained in the cdr, event and group tags. 
Each CDR represents the call in the view of one PBX object. So there might be multiple CDRs for one call if multiple PBX objects are used within the call.

* '''cdr fields:''' id, guid, sys, pbx, node, device, cn, e164, h323, dir, utc, local.
* '''event fields:''' id, msg, type, e164, h323, conf, cause, time, cdr_id, order_index.
* '''group fields:''' id, name, active, type, cdr_id.

'''id''' field is assigned by postgresql for each entry and has nothing to do with the information present in the cdr. It is different for each entry inside the table.

The events table has two additional fields, called cdr_id, to associate these events to the corresponding cdr entry and order_index to keep their position inside the cdr.
Groups table has also the cdr_id field to associate the group entries to the corresponding cdr and events entries.

The '''cdr_properties''' table contains relevant information associated with the call such as call_length, alert_length or call_flow. It also presents a cdr_id field.

====filters====

This section is composed by three tables: filter_columns, filter_conditions and filters.

* '''filter_columns''' is not used for the time being. This is supposed to contain the columns the user wants to see in his report, but right now, just default columns (Time/Object/Duration/Left/Direction/State/Right) are shown.
* '''filter''' contains the filter name and description plus two conditions call_state (No Response, Connected, Busy and No Channel) and direction (Incoming, Outgoing, Transfer and Call Forward).
* '''filter_conditions''' contains the defined conditions for a filter

All three tables are related through an id.

====cdr_users====

This table contains a timestamp '''missed_calls_time''' for the last report access by a user '''cn''' + ('''pbx''' OR '''sys''') with mypbx. It is used to retrieve information about missed calls since the last use of mypbx. 
The timestamp '''clear_report_time''' indicates the last clearance time. 
email, sys (system name) and pbx (PBX name) are also stored for each user.

====replication====

Contains information of the last replication run, which is used to sync master/standby installations.

===Replication===

The replication between the master and standby servers is divided into two steps:

====CDRs====
Both master and standby server keep an information about the last replicated CDR. From this CDR on, they retrieve all CDR guids (32 bytes) from all new CDRs from the other server. If a guid already exists in the local database, the CDR is skipped, otherwise it is replicated. 
So there is a minimal data exchange for already existing CDRs and each new CDR is only processed once.

====Filters/LDAP/Report Mails/Users====
The master server does nothing here, but the '''standby''' deletes all filters, LDAP servers, report mails and users and replicates all from the master. 
So these items from the master server can be used, but not changed, on the standby server.

===Remote Interface===

You can retrieve the PDF/XML/CSV report with a remote interface. 
Make a POST or GET HTTP request to '''http(s)://Linux-IP/apps/innovaphone-reporting/report.php''' with the following parameters:

* remote: mandatory for a remote request!
** '''1'''
* from : the from date/time as UNIX timestamp '''OR''' date/time string as described [ http://www.php.net/manual/de/datetime.formats.php | here ].
* to: the to date/time (format see '''from''')
* [format]: the return format, allowed values:
** '''xml''': default
** '''pdf'''
** '''csv'''
* [sortby] : the report sorting, allowed values:
** '''time''': default
** '''obj''': sort by pbx object name
** '''call-duration'''
** '''alert-duration'''
** '''dir''': sort by call direction
* [sortorder]: the report sort order, allowed values:
** '''ascending''': default
** '''descending'''
* [groupby]: report grouping
** default empty/not set: no grouping
** '''local_stamp''': group by time
** '''cn''': group by pbx object name
* [hidedigits]: hide the last X digits of external numbers
* pbx: search for this PBX (mandatory!)
* pbxobject: search for this PBX object (you can leave this, if you use filterX)
* filterX: use a filter with its name. You can use multiple filters with filter1=test, filter2=test2...
* [filterinfo]: show the filter information in a created report ("true" or "false")
* [lang]: the language, e.g. "en" or "de"
* [displayedduration]:
** '''call_duration''': default Call Duration (Total)
** '''conn_duration''': Call Duration (User)
** '''billing_duration''': Billing Duration
* [anonym]: anonymize internal names/numbers ("true" or "false")
* [bulk]: creates user reports (see [[ #Report_Mails | Report Mails ]])
* [sender]: sender email adress of the report
* [confid]: query calls of a certain conference ID
** you can omit the following fields, if using confid: '''from''', '''to''', '''pbx''', '''pbxobject''', '''filterX'''

Parameters in [] are optional.

'''pbxobject''' supports [[ #PostgreSQL_Patterns | PostgreSQL Patterns ]].

Example:
https://172.16.14.123/apps/innovaphone-reporting/report.php?remote=1&from=2011-03-29&to=2011-03-30&format=xml&pbxobject=Saturn
Gets all records between 2011-03-29 and 2011-03-30 for the pbx object Saturn.

Example:
https://172.16.14.123/apps/innovaphone-reporting/report.php?remote=1&from=2011-03-29&to=2011-03-30&format=xml&filter1=test&filter2=test2
Gets all records between 2011-03-29 and 2011-03-30 for the filters test and test2.

===Tools===

====NetDrive====

[http://www.heise.de/software/download/netdrive/55134 NetDrive] is a usefull webdav client, which can be used to access webdav of the innovaphone application platform.

====PGAdmin====

[http://www.pgadmin.org/ PGAdmin] is an administration tool for PostgreSQL databases.

====Putty====

[http://www.putty.org/ Putty] is SSH client to connect to the linux application platform.

===Call list icons===
The direction of the icon arrow depends on the call flow.

* [[Image:reporting_conn.jpg]]: a connected call
* [[Image:reporting_busy.jpg]]: busy destination
* [[Image:reporting_no_res.jpg]]: no response from destination
* [[Image:reporting_error.jpg]]: an error occurred, like "no channel available" during the call setup
* [[Image:reporting_ct.jpg]]: call transfer
* [[Image:reporting_cct.jpg]]: call transfer with consultation
* [[Image:reporting_cf.jpg]]: call forward
* [[Image:Reporting_pickup.jpg]]: call pickup (or SOAP redirect)
* [[Image:reporting_dir.jpg]]: call direction

A small arrow on a call state icon indicates a callback done with mxPBY, e.g.:
* [[Image:reporting_busy_callback.jpg]]

==Known Problems==
===Replication===
====Callback information====
The callback information get lost in the following scenario:
* The callback CDR is already replicated on both master and standby
* Master or standby is down
* A user calls back the CDR from point 1

====Missed calls====
The information for missed calls is not replicated. So the first time, a standby server is used with mypbx, the missed calls information will be wrong. The second time will be correct again.

===CDRs===
If the innovaphone Reporting is not running, for whatever reaseon, the device, which sends CDRs, currently stores up to 300kB CDRs data. So if one CDR has up to 2kB, 150 CDRs can be stored until the innovaphone Reporting should be up again, to avoid data loss.

===Missing values for PBX drop down box===
If your database currently contains no CDRs of one of your PBX systems, you won't be able to select this system as PBX for report creation or report mail configuration!

===Restoring Database with more than 2GB===

When restoring database using the web browser there is a 2GB upload limit, so if our database have a bigger size the upload will fail.

As alternative solution (if there is enough space):

1. Copy the gz database dump to the webdav folder
2. Uncompress this dump: /bin/gzip -cd /var/www/innovaphone/webdav/dump.gz --uncompress > /tmp/db.dump
3. Start the restore: /usr/local/bin/config.sh postgres db-restore /tmp/pg_schema.dump /tmp/db.dump innovaphone-reporting
4. be patient, this might take a while
5. delete /tmp/db.dump, /var/www/innovaphone/webdav/dump.gz and /tmp/pg_schema.dump (automatically created)

===PDF generation for many CDRs may fail===
You may experience a '''Server error 500''' if you generate PDFs with many CDRs. The PDF library which is used to generate the PDFs fails.
Please generate multiple PDFs with a smaller timespan in such a case.

== Related Articles ==

[[Howto:Integration_reporting_and_voice_recording]]

[[Category:Concept|Reporting]]

Reference10:Concept Reporting

2016-10-19T11:16:02Z

Tru: /* Report XML */

==Requirements==

It is needed to have the [[Reference10:Concept_Linux_Application_Platform|application platform]] installed and running.

===Calculation of required disk space===

An average CDR requires 2080 bytes of disk space inside the database. 
So '''one GB''' disk space is needed for ~'''516222 CDRs'''. 
One call may have one or multiple CDRs depending on the call flow, the used PBX objects and their configuration.


It is strongly recommended that you try to precalculate your required disk space and configure a suiting value under [[#Configure_scheduled_CDR_cleanup]]. 
Don't forget to configure the alarm server under [[Reference10:Concept_Linux_Application_Platform#Alarm_Server]] to receive an alarm if the disk is nearly full (10% disk space remaining).


==Installation==

Download the latest version of innovaphone reporting.

Log into the application platform, go to the Applications tag, click on [[ Reference10:Concept_Linux_Application_Platform#Upload.2FUpdate|Upload/Update]] and upload the downloaded file.
The installation will start automatically and the page will refresh every two seconds showing the installation process.
If there is no error during the installation you will see at the end "Installation was succesfull". Otherwise,
you will get "installation failed" and the reason why it went wrong.

===Hotfix===
If you have already installed the latest version of Reporting, simply download the Reporting...HotfixIncremental for your platform (VM or IPxx10) or if you have missed some hotfixes, download the Reporting...HotfixCumulative archive, which contains all hotfixes since hotfix1.
 
 
Upload this hotfix archive [[Reference10:Concept_Linux_Application_Platform#Upload.2FUpdate|here]].

==Configuration==
===Device===

====License====
It is required to have a Reporting license installed on your device. Check under [[ Reference10:General/License ]] if you already have one.

Set the Reporting flag for each PBX object, which should be reported on the objects properties page.

====CDR Gateway====
Any innovaphone device which sends [[Reference10:Concept_Call_Detail_Record_CDR_PBX|CDRs]] to the reporting application must have at least one CDR interface configured under [[ Reference10:Gateway/CDR ]]:

* Type: LOCAL-AP or REMOTE-AP/REMOTE-AP-S

If HTTP/HTTPS is selected then some other parameters must be set:

* Address: ip address of the application platform
* Port: 80 for REMOTE-AP
* Port: 443 for REMOTE-AP-S
* Method: POST/GET
* Path: ap/cdr.fcgi

The application platform is by default password protected, so you'll have to perform one of these steps: 

* configure an authenticated URL for '''ap/cdr.fcgi''' under [[ Reference10:Services/HTTP/Client ]] (recommended)
** If you configure an authenticated URL (with the linux webserver credentials), don't forget to configure port 80 or port 443 for secure transport (Remote-AP-S) like https://111.111.111.111:443/ap or http://111.111.111.111:80/ap
* configure '''ap/cdr.fcgi''' as public web path on the innovaphone application platform [[ Reference10:Concept_Linux_Application_Platform#Change_web_server_properties_and_public_access_to_the_web.2Fwebdav|Public Web Paths ]]

Configure a second CDR interface, if you use [[#Replication|Replication]].

====Enable PBX CDRs====
Enable the "Generate CDRs" flag under [[ Reference10:PBX/Config/General ]].

===innovaphone Application Platform===

If the reporting URL/user/password is not configured in your device as authenticated URL, configure '''ap/cdr.fcgi''' as public web path on the innovaphone application platform [[ Reference10:Concept_Linux_Application_Platform#Change_web_server_properties_and_public_access_to_the_web.2Fwebdav|Public Web Paths ]].

===Database===

Reporting creates the innovaphone-reporting database to store CDRs sent from any innovaphone devices (appendix 7.6 explains the database structure).
PostgreSQL is also available for other applications and any of them could create its own database.

====Password====

Reporting creates the database user '''innovaphone-reporting''' with default password '''reporting'''.
This password may be changed at the innovaphone Reporting page under Config/Database.

====Remote Access====

There are tools (PgAdmin III) that allow to connect to application databases remotely.
It is first needed to configure the IP you are connecting from under Config/Database at the innovaphone reporting page.

For the PgAdmin III it is imporant to use innovaphone-reporting as Service-DB (Wartungs-DB). Default login credentials - User: innovaphone-reporting - Password: reporting

====Delete CDRs====

You can delete CDRs for certain/all users in a certain timespan. If you enter '''%''' as object, all users are selected.

Note that PostgreSQL doesn't free the space on the disk! If you need free disk space, issue this command on the shell:
''sudo -u postgres vacuumdb -f innovaphone-reporting''
This may take some time and CDRs won't be received during this time.

====Configure scheduled CDR cleanup====

If you activate scheduled cleanup, CDRs older than the configured amount of months will be automatically deleted. 
The scheduled task is started once a day at 2 AM.

===PBX===

If you use multiple PBX devices which are not Master/Slave, you have to select, which identifier is unique for a user under Config/PBX:
* System Name (default)
* PBX Name

The selected value determines, which values are shown in the PBX dropdown box for report creation or report mail configuration.

===Replication===

You can configure a second innovaphone application platform with an installed innovaphone Reporting for replication purposes. 

* Mode:
** '''Off''': no replication
** '''Master''': the local server is the master server
** '''Standby''': the local server is the standby server, filters will be replicated from the master and can't be changed here
* Master/Standby Server: the IP address of the master or standby server
* Database password: the PostgreSQL database password of the other server (default is '''reporting''').
* Synchronisation interval: the interval in minutes (range 1-60) in which a sync is done

Now configure a second [[#CDR_Gateway|CDR Gateway]] for the standby server.

The current status can be seen here too. If the status is '''Failed''' take a look at the log file '''innovaphone Reporting Replication''' under [[ Reference10:Concept_Linux_Application_Platform#Logs|Diagnostics/Logs]] or look at the last trace output at the bottom of the page.
 
 
How replication works is described [[#Replication_2|here]].

===LDAP===

Several LDAP servers and dialing locations can be configured here. 

PBX field must correspond to a name of a PBX since PBX's names are available in CDRs. The received CDR is parsed to get the PBX name and this name will be used to find the corresponding LDAP server and dialing location needed to resolve names.

Each configured LDAP server and dialing location can be activated/deactivated with the '''active''' flag.

[[Image:ldap_update.png]]

If the country where you configure LDAP does not have Trunk/National prefix you should leave "National Prefix" and "Area Code" empty.

In the number Attributes field please do '''not''' add any additional characters to the attributes like ":P", ":D" or "@", for instance "homePhone:P, mobile:M, telephoneNumber:D". This does not work. That would be correct: "homePhone, mobile, telephoneNumber"

LDAP Internal Search flag allows reporting to perform name resolution also for internal numbers.

===Report Mails===

Automatic report generation can be configured here:

* '''time''': daytime at which the report is sent
* '''user reports''':
** Creates for each matching user a separate report
** Users are matched by '''Object (Long Name)'''
** A user report only contains calls for this user
** The email address of the user is built by its '''H323 name''' and the '''System Name''' of its PBX (h323@systemname) or determined by the E-Mail field of the user
* '''interval''':
** daily: Mail will be send daily with the automatic period "last day"
** weekly: Mail will be send weekly with the automatic period "last week"
** monthly: Mail will be send daily with the automatic period "last month"
* '''day''': the day, at which the report is sent
* '''mail adresses''': recipients of the report (comma separated)
* '''Sender E-Mail address''': sender email address, which may be present as [[ Reference10:Concept_Linux_Application_Platform#Relay_Hosts | relay host ]]
* '''compress''': compress the attachment or not
* '''sort by'''
* '''sort order'''
* '''language'''
* '''send time''': the time of a day, when the report is sent

The explanation for the other settings can be found [[ #Report_Creation | here. ]] 

[[Image:mails.png]]

===Users===

You can configure multiple users, who shall have access to reports without having access to the whole reporting configuration. 
The user can login with his user name and password on: 

http(s)://Linux-IP/apps/innovaphone-reporting/user/login.php

The admin can assign one or more base filters to the user. A base filter is explained [[ #Base_filter | here]]. 
If the user creates new reports, new own filters or report mails, he '''has''' to use one of his assigned base filters.

If you are using multiple PBX systems, the user has only access to these systems, which are configured in the base filters of the user.
If the user has no base filter with a limitation to a certain "System Name"/"PBX Name" (depends on your [[ #PBX | PBX configuration ]]),
he will have access to all systems!

[[Image:users.jpg]]

====User Login====

A logged in user can create reports, own filters and report mails based on his assigned base filters.

[[Image:Userlogin.jpg]]

===Images===

You may upload images to be used as logo or footer in pdf reports. 

Logos must be 32x32 and footer can have a maximum width of 450 pixels and a maximum height of 50 pixels. 

These images can have jpeg or png format. 

===Relay CDRs===

Relay CDRs can be stored in log files by the Reporting application. Configure a CDR gateway as already described and relay CDRs will be written to the webdav file '''/cdr/cdr.txt'''.
The file is rotated on 1 MB size. The first rotated file is uncompressed, further files will be gz compressed. Max ten files are kept. Older files will be deleted: 
* cdr.txt
* cdr.txt.1
* cdr.txt.2.gz
* cdr.txt.3.gz
* cdr.txt.4.gz
* cdr.txt.5.gz
* cdr.txt.6.gz
* cdr.txt.7.gz
* cdr.txt.8.gz
* cdr.txt.9.gz

===innovaphone-reporting web access===

You can configure a separate authentication for the innovaphone-reporting web site [[Reference10:Concept_Linux_Application_Platform#Change_application_access_credentials|here]]. 
One can just login on the reporting site with this access.

===Integration Voice recorder===

The innovaphone voice recording can be integrated and a remote control of the player is possible, see relative article.

==Filters==
===General===

Filters are set up to create reports based on certain conditions. A filter can have multiple conditions and multiple filters can be combined on report creation (combine is performed with an '''OR'''). 
A filter has a unique '''name''' with an optional '''description'''.

===Conditions===

[[Image:filter.png]]

There are five or seven condition sections depending on what is selected under '''States'''. Conditions inside same section are '''OR''' associated while different sections are '''AND''' associated.
 

(Object == Terra '''OR''' Object == Uranus) '''AND''' (PBX == sifi) '''AND''' (Number == 0049%)

====Base filter====

If you select another filter as base filter, the conditions of the base filter are implicitly '''AND''' conjuncted, when the current filter is used. 
So if the base filter defines two PBX values, e.g. "Berlin" and "Hamburg" and the current filter defines one PBX value, e.g. "Berlin", only objects of the PBX "Berlin" will be filtered: 

(pbx="Berlin") AND (pbx="Berlin" OR pbx="Hamburg")

If a user defines an own filter for his reports, he has to use a base filter, which he is allowed to use. So each filter, which he uses, will have at least one base filter condition, which the admin has defined.

You have to take care with the conditions of the current filter and the base filter,
as it is now easy to create a filter with mutually exclusive conditions, e.g. if
the filter has pbx="Berlin" and the base filter pbx="Hamburg" => no matching records.

====Anonym====

If you check this flag, a report created with this filter or with a filter, where this filter is a basefilter, will by anonymized.

====Local====

Define one ore more conditions for the local party, defined by:

* Object: the cn/PBX object name
* Number: the number
* Groups: a group of the PBX object

====Remote====

Define one or more conditions for the remote party, defined by:

* Number: the number
* Remote display name: the display name

====PBX====

Define one ore more conditions for the PBX, defined by:

* PBX: the PBX name
* Node: the node name

====States====

* No Response
* Connected
* Busy
* No Channel

====Directions====

* Incoming
* Outgoing
* Transfer: calls, which have been transferred to the current local party
* Call Forward: calls, which have been forwarded to the current local party

====Call Duration====

Time the call was connected.

This condition will be '''AND''' with the others if all '''States''' are selected. 
If Busy, No Channel or No Response is unselected, then the filter will search for Connected calls with connected time greater or smaller than '''Call Duration'''.

====Alert Duration====

Time the call was ringing independent of the status of the call afterwards.

This condition will be '''AND''' with the others if all '''States''' are selected. 
If Busy, No Channel or Connected is unselected, then the filter will search only for Not Connected Calls that were ringing more or less time than '''Alert Duration'''.

====Report times====

Define the time where calls should be counted. 
You can optionally define the weekday(s) of calls.

====Images====

* Logo: This must be 32x32 pixel image in jpeg or png format. 
* Footer: Maximum width of 450 pels and maximum height of 50 pels. Also jpeg or png format. 

====Using Patterns====

You can use these [[ #PostgreSQL_Patterns | PostgreSQL Patterns ]] for every condition.

==Report Creation==
===General===

It is possible to generate call lists for single users or more complex reports by means of filters.

===Web Interface===

Reporting application provides a web interface to generate reports.

[[Image:Report_hide.png]]

* '''PBX''': select the PBX for the report. The values of the drop down box depend on your [[#PBX | PBX configuration]]
* '''Object (Long Name)''': corresponds to the PBX Long Name assigned to a specific user (% is a special postgresql character, which matches any string)
* '''Filter''': one or multiple filters can be defined ('''OR''' joined)
* '''Group by''': the result can be grouped by Date or Object
* '''Hide last X digits''': you may replace the last digits of an external number with a '*'.
** LDAP must be configured in order to use this capability but if you want no LDAP funtionality, just unset the Active Box in LDAP.
** Actually, the pbx/phys value of a call is matched against the LDAP pbx value and if the number starts with the external line prefix.
* '''Anonym''': do not show internal names/numbers
** If anonym is set, hide last digits is set to 3, if not set
* '''Filter Info''': the report will contain information about the configured settings and filter information
* '''Displayed Duration''':
** Call Duration (Total): the total call duration, e.g. with the duration of a subsequent transfer
** Call Duration (User): just the time, the user was connected
** Billing Duration: the duration, a user must be billed for
** None of these durations contain the alert duration, which is separatly listed

[[Image:reporting_report.png | A normal report. The summary shows incoming / outgoing summaries]]

[[Image:grouped_report.png | A grouped report. Each group has an own summary]]

====Print====

Click the print icon to open a printable version of the report.

====Save====
You can save the report as '''pdf''' or as '''xml''' by using the corresponding icon. 
You can also download a report in '''csv''' format without call history. The report uses '''comma''' as delimeter character, '''"''' as text qualifier and '''PBX Object/Remote Party''' columns should be defined as Text (avoid telephone numbers to be considered as numbers by Excel). '''UTF-8''' must be used as character set. 

====Sorting====

Each sortable column has a clickable column head. This sorting will be also used when opening the printable version or saving the report as PDF.

====Icons====
The icons are explained in the [[#Call list icons|appendix]].

===Remote Interface===

See [[#Remote_Interface_2|Remote Interface Appendix]]

==Backup and Restore==

You can both manually and automatically backup the database and configuration files for Reporting under [[Reference10:Concept_Linux_Application_Platform#Backup|Administration/Backup]] in the application platform.

Configuration details for the update server can be found [[Reference10:Concept_Linux_Application_Platform#Backup|here]].

===Configuration Files===

'''saveinnovaphone-reportingcfgs''' is the command used to automatically save configuration files with the [[Reference10:Concept_Linux_Application_Platform#Command_File|Command File]].

===Data===

'''saveinnovaphone-reportingdb''' is the command to automatically backup the whole innovaphone Reporting database with the [[Reference10:Concept_Linux_Application_Platform#Command_File|Command File]].

If you restore the reporting database, you should keep in mind, that this might take several hours for a system
on a CF card, depending on the size of the restored database. The backup process itself is quite fast with a few minutes.

===Logs===

'''saveinnovaphone-reportinglogs''' to save log files with the [[Reference10:Concept_Linux_Application_Platform#Command_File|Command File]].

==Appendix==
===PostgreSQL Patterns===
For filter conditions or for the pbx object value you can use the following patterns inside a string:

* '''%''': matches any string of zero or more characters
* '''_''': matches any single character

Example:
'''Sat%''' will match all pbx objects, which start with the string '''Sat'''.

We do always perform case insensitiv searches!

===innovaphone Reporting XML===
<code type="xml">
<?xml version="1.0" encoding="utf-8"?>
<application>
<name>innovaphone Reporting</name>
<desc>Reporting software</desc>
<directory>innovaphone-reporting</directory>
<href>report.php</href>
<linux-username>innovaphone-reporting</linux-username>
<packages>
<package>php5-gd</package>
<package>php5-ldap</package>
</packages>
<database name="innovaphone-reporting" username="innovaphone-reporting"/>
<cronjobs>
<cronjob script="/etc/cron.d/reporting_replication"/>
<cronjob script="/etc/cron.d/reporting_cleanup"/>
<cronjob script="/etc/cron.d/reporting_mails"/>
</cronjobs>
<log-files>
<log title="Postgresql-8.4" no-clear="true">/var/log/postgresql/postgresql-8.4-main.log</log>
<log title="Reporting cleanup">/var/www/innovaphone/apps/innovaphone-reporting/log/reporting_cleanup.log</log>
<log title="innovaphone Reporting">/var/www/innovaphone/apps/innovaphone-reporting/log/innovaphone-reporting.log</log>
<log title="innovaphone Reporting Replication">/var/www/innovaphone/apps/innovaphone-reporting/log/reporting_replication.log</log>
</log-files>
<config-files>
<conf>/etc/postgresql/8.4/main/pg_hba.conf</conf>
<conf>/etc/postgresql/8.4/main/postgresql.conf</conf>
<conf>/home/innovaphone-reporting/reporting.conf</conf>
<conf>/home/root/ssl_cert/server.key</conf>
<conf>/home/root/ssl_cert/server.crt</conf>
<conf>/etc/cron.d/reporting_replication</conf>
<conf>/etc/cron.d/reporting_cleanup</conf>
<conf>/etc/cron.d/reporting_mails</conf>
<conf>/var/www/innovaphone/apps/innovaphone-reporting/report_images</conf>
</config-files>
<backup>
<command title="Save innovaphone Reporting configuration files" cmd="saveinnovaphone-reportingcfgs" script=""/>
<command title="Save innovaphone Reporting database" cmd="saveinnovaphone-reportingdb" script=""/>
<command title="Save innovaphone Reporting log files" cmd="saveinnovaphone-reportinglogs" script=""/>
</backup>
<restore>
<command title="Restore innovaphone Reporting configuration files" cmd="restoreinnovaphone-reportingcfgs" script="">
<action>/etc/init.d/postgresql restart</action>
<action>/etc/init.d/cron restart</action>
</command>
<command title="Restore innovaphone Reporting database" cmd="restoreinnovaphone-reportingdb" script=""/>
</restore>
<uninstall script="/usr/bin/sudo /usr/local/bin/uninstall_script.sh -f 'innovaphone-reporting.xml' -linux_user yes -linux_group yes -database yes -database_user yes -log_script '/var/www/innovaphone/log/appl_uninstall.log'">
<to-delete>
<to-del path="/usr/local/bin/reporting_cleanup.sh"/>
<to-del path="/usr/local/bin/reporting_replication.out"/>
<to-del path="/usr/local/bin/reporting_replication.sh"/>
<to-del path="/home/innovaphone-reporting/tmp"/>
</to-delete>
</uninstall>
<lighttpd-auth>1</lighttpd-auth>
<public-web-paths>
<path>mypbx</path>
<path>user</path>
</public-web-paths>
</code>

===Installed Debian Packages===

The following packages (and their dependencies) are installed with innovaphone Reporting:

* php5-gd
* php5-ldap

===Configuration Files===

pg_hba.conf is the client authentication configuration file and controls which hosts are allowed to connect, how clients
are authenticated, which PostgreSQL user names they can use and which databases they can access.

postgresql.conf is the PostgreSQL configuration file

===Data Files===

If you backup the innovaphone reporting database, you'll get a gz archiv, which contains the whole innovaphone-reporting database.

===Report XML and CSV===
The field description below applies for the '''XML''' and '''CSV''' columns!

<code type="xml">
<report>
<record>
....
<time time="1301303966" utc="1301303966">2011-03-28 11:19:26</time>
<obj>Saturn</obj>
<id>870998fee909d311b2ec009033105dc9</id>
<call>int</call>
<alert-duration seconds="0">0:00</alert-duration>
<flow>
<ev caller="ep1" ep1_number="101" ep1_name="saturn" ep1_dn="Saturn"
ep2_number="102" ep2_name="uranus" ep2_dn="Uranus" status="co" entry="true"/>
</flow>
<call-duration seconds="2">0:02</call-duration>
<billing-duration seconds="2">0:02</billing-duration>
<conn-duration seconds="2">0:02</conn-duration>
<groups>
<group>test</group>
<group>test2</group>
</groups>
<node>root</node>
<pbx>.</pbx>
<cause></cause>
<dir>o</dir>
<status>co</status>
<type/>
<remote number="102" name="uranus" dn="Uranus"/>
<callback number="456" name="abc" dn="123" time="1301305962">2011-03-28 11:52:42</callback>
</record>
....
</report>
</code>

* time: the node contains a formatted time string of the local time
** attribute '''time''' is a unix timestamp (referring to the local time stamp of the CDR)
** attribute '''utc''' is a unix timestamp (referring to the utc time stamp of the CDR)
* obj: the PBX object name (also called cn)
* id: the conference id of the call
* call: '''int''' (internal) or '''ext''' (external) call
* flow '''(XML only)''': the call flow
** ev
***ep1 (ep1_number, ep1_name, ep1_dn): the left side of the call
***ep2 (ep2_number, ep2_name, ep2_dn): the right side of the call
***caller: '''ep1''', '''ep2''' or empty, if unknown
***status: '''co''' (connected), '''al''' (alert), '''er''' (error) or '''bu''' (busy) state of the current event
***entry: '''true''' for the entry event of the local object
***type: '''cf''' (call forward), '''ct''' (call transfer)
* Original Called '''(CSV only)''': In case of Call flow; The original called device
* Diverting '''(CSV only)''': In case of Call flow; The diverting device
* Transferring '''(CSV only)''': In case of Call flow; The transferring device
* groups '''(XML only)''': the groups of the PBX object
* node: the node of the PBX object
* pbx: the pbx of the PBX object
* cause: the decimal disconnect reason of the call (see [[Reference:ISDN_Cause_Codes]])
* remote:
** outgoing calls -> dialed endpoint
** incoming calls -> first ep2 above entry event or entry event if this is the first one
** incoming calls with incoming transfer after entry event -> transfer target
* status:
** outgoing calls -> best found status in call flow
** incoming calls -> status of entry event
* type: the type of the entry event or, if not set, the type of the next event, if given
** empty: direct call
** '''ct''': call transfer
** '''cf''': call forward
** '''cct''': call transfer with consultation
** '''pu''': call pickup
* dir: o (outgoing) if the first event is the entry event and the caller is ep1
* dir: i (incoming) if not o
* alert-duration: alert time
* billing-duration: outgoing call -> duration from the first event until the last event in the flow
* billing-duration: incoming call -> duration from the first transfer/forward event until the last event in the flow
* call-duration: duration of the whole call
* conn-duration: duration from the entry event until the event, where the local endpoint isn't connected any more
* callback: '''name''', '''number''', '''dn''' and '''time''' if this call has been callbacked using mypbx (time referrs to the UTC time of the callback)
* Further Registration: If more than one devices is registered to the same object, each device creates a CDR. This field identifies the additional CDRs for the same call
* Object Info '''(CSV only)''': combination of object names and number
* Date '''(CSV only)''': extracted date only from the time_string
* Time_2 '''(CSV only)''': extracted time only from the time_string

===Database Structure===

====cdrs====
Each received cdr-xml is formed by a cdr tag and an undefined number of event and group tags.
(Refer to: [[Reference10:Concept_Call_Detail_Record_CDR_PBX|CDR]])

This section is composed by four tables: cdrs, events, groups and cdr_properties.
The first three tables contain the corresponding fields to store the information contained in the cdr, event and group tags. 
Each CDR represents the call in the view of one PBX object. So there might be multiple CDRs for one call if multiple PBX objects are used within the call.

* '''cdr fields:''' id, guid, sys, pbx, node, device, cn, e164, h323, dir, utc, local.
* '''event fields:''' id, msg, type, e164, h323, conf, cause, time, cdr_id, order_index.
* '''group fields:''' id, name, active, type, cdr_id.

'''id''' field is assigned by postgresql for each entry and has nothing to do with the information present in the cdr. It is different for each entry inside the table.

The events table has two additional fields, called cdr_id, to associate these events to the corresponding cdr entry and order_index to keep their position inside the cdr.
Groups table has also the cdr_id field to associate the group entries to the corresponding cdr and events entries.

The '''cdr_properties''' table contains relevant information associated with the call such as call_length, alert_length or call_flow. It also presents a cdr_id field.

====filters====

This section is composed by three tables: filter_columns, filter_conditions and filters.

* '''filter_columns''' is not used for the time being. This is supposed to contain the columns the user wants to see in his report, but right now, just default columns (Time/Object/Duration/Left/Direction/State/Right) are shown.
* '''filter''' contains the filter name and description plus two conditions call_state (No Response, Connected, Busy and No Channel) and direction (Incoming, Outgoing, Transfer and Call Forward).
* '''filter_conditions''' contains the defined conditions for a filter

All three tables are related through an id.

====cdr_users====

This table contains a timestamp '''missed_calls_time''' for the last report access by a user '''cn''' + ('''pbx''' OR '''sys''') with mypbx. It is used to retrieve information about missed calls since the last use of mypbx. 
The timestamp '''clear_report_time''' indicates the last clearance time. 
email, sys (system name) and pbx (PBX name) are also stored for each user.

====replication====

Contains information of the last replication run, which is used to sync master/standby installations.

===Replication===

The replication between the master and standby servers is divided into two steps:

====CDRs====
Both master and standby server keep an information about the last replicated CDR. From this CDR on, they retrieve all CDR guids (32 bytes) from all new CDRs from the other server. If a guid already exists in the local database, the CDR is skipped, otherwise it is replicated. 
So there is a minimal data exchange for already existing CDRs and each new CDR is only processed once.

====Filters/LDAP/Report Mails/Users====
The master server does nothing here, but the '''standby''' deletes all filters, LDAP servers, report mails and users and replicates all from the master. 
So these items from the master server can be used, but not changed, on the standby server.

===Remote Interface===

You can retrieve the PDF/XML/CSV report with a remote interface. 
Make a POST or GET HTTP request to '''http(s)://Linux-IP/apps/innovaphone-reporting/report.php''' with the following parameters:

* remote: mandatory for a remote request!
** '''1'''
* from : the from date/time as UNIX timestamp '''OR''' date/time string as described [ http://www.php.net/manual/de/datetime.formats.php | here ].
* to: the to date/time (format see '''from''')
* [format]: the return format, allowed values:
** '''xml''': default
** '''pdf'''
** '''csv'''
* [sortby] : the report sorting, allowed values:
** '''time''': default
** '''obj''': sort by pbx object name
** '''call-duration'''
** '''alert-duration'''
** '''dir''': sort by call direction
* [sortorder]: the report sort order, allowed values:
** '''ascending''': default
** '''descending'''
* [groupby]: report grouping
** default empty/not set: no grouping
** '''local_stamp''': group by time
** '''cn''': group by pbx object name
* [hidedigits]: hide the last X digits of external numbers
* pbx: search for this PBX (mandatory!)
* pbxobject: search for this PBX object (you can leave this, if you use filterX)
* filterX: use a filter with its name. You can use multiple filters with filter1=test, filter2=test2...
* [filterinfo]: show the filter information in a created report ("true" or "false")
* [lang]: the language, e.g. "en" or "de"
* [displayedduration]:
** '''call_duration''': default Call Duration (Total)
** '''conn_duration''': Call Duration (User)
** '''billing_duration''': Billing Duration
* [anonym]: anonymize internal names/numbers ("true" or "false")
* [bulk]: creates user reports (see [[ #Report_Mails | Report Mails ]])
* [sender]: sender email adress of the report
* [confid]: query calls of a certain conference ID
** you can omit the following fields, if using confid: '''from''', '''to''', '''pbx''', '''pbxobject''', '''filterX'''

Parameters in [] are optional.

'''pbxobject''' supports [[ #PostgreSQL_Patterns | PostgreSQL Patterns ]].

Example:
https://172.16.14.123/apps/innovaphone-reporting/report.php?remote=1&from=2011-03-29&to=2011-03-30&format=xml&pbxobject=Saturn
Gets all records between 2011-03-29 and 2011-03-30 for the pbx object Saturn.

Example:
https://172.16.14.123/apps/innovaphone-reporting/report.php?remote=1&from=2011-03-29&to=2011-03-30&format=xml&filter1=test&filter2=test2
Gets all records between 2011-03-29 and 2011-03-30 for the filters test and test2.

===Tools===

====NetDrive====

[http://www.heise.de/software/download/netdrive/55134 NetDrive] is a usefull webdav client, which can be used to access webdav of the innovaphone application platform.

====PGAdmin====

[http://www.pgadmin.org/ PGAdmin] is an administration tool for PostgreSQL databases.

====Putty====

[http://www.putty.org/ Putty] is SSH client to connect to the linux application platform.

===Call list icons===
The direction of the icon arrow depends on the call flow.

* [[Image:reporting_conn.jpg]]: a connected call
* [[Image:reporting_busy.jpg]]: busy destination
* [[Image:reporting_no_res.jpg]]: no response from destination
* [[Image:reporting_error.jpg]]: an error occurred, like "no channel available" during the call setup
* [[Image:reporting_ct.jpg]]: call transfer
* [[Image:reporting_cct.jpg]]: call transfer with consultation
* [[Image:reporting_cf.jpg]]: call forward
* [[Image:Reporting_pickup.jpg]]: call pickup (or SOAP redirect)
* [[Image:reporting_dir.jpg]]: call direction

A small arrow on a call state icon indicates a callback done with mxPBY, e.g.:
* [[Image:reporting_busy_callback.jpg]]

==Known Problems==
===Replication===
====Callback information====
The callback information get lost in the following scenario:
* The callback CDR is already replicated on both master and standby
* Master or standby is down
* A user calls back the CDR from point 1

====Missed calls====
The information for missed calls is not replicated. So the first time, a standby server is used with mypbx, the missed calls information will be wrong. The second time will be correct again.

===CDRs===
If the innovaphone Reporting is not running, for whatever reaseon, the device, which sends CDRs, currently stores up to 300kB CDRs data. So if one CDR has up to 2kB, 150 CDRs can be stored until the innovaphone Reporting should be up again, to avoid data loss.

===Missing values for PBX drop down box===
If your database currently contains no CDRs of one of your PBX systems, you won't be able to select this system as PBX for report creation or report mail configuration!

===Restoring Database with more than 2GB===

When restoring database using the web browser there is a 2GB upload limit, so if our database have a bigger size the upload will fail.

As alternative solution (if there is enough space):

1. Copy the gz database dump to the webdav folder
2. Uncompress this dump: /bin/gzip -cd /var/www/innovaphone/webdav/dump.gz --uncompress > /tmp/db.dump
3. Start the restore: /usr/local/bin/config.sh postgres db-restore /tmp/pg_schema.dump /tmp/db.dump innovaphone-reporting
4. be patient, this might take a while
5. delete /tmp/db.dump, /var/www/innovaphone/webdav/dump.gz and /tmp/pg_schema.dump (automatically created)

===PDF generation for many CDRs may fail===
You may experience a '''Server error 500''' if you generate PDFs with many CDRs. The PDF library which is used to generate the PDFs fails.
Please generate multiple PDFs with a smaller timespan in such a case.

== Related Articles ==

[[Howto:Integration_reporting_and_voice_recording]]

[[Category:Concept|Reporting]]

Reference10:Concept Reporting

2016-10-17T10:28:25Z

Tru: /* Report XML */

==Requirements==

It is needed to have the [[Reference10:Concept_Linux_Application_Platform|application platform]] installed and running.

===Calculation of required disk space===

An average CDR requires 2080 bytes of disk space inside the database. 
So '''one GB''' disk space is needed for ~'''516222 CDRs'''. 
One call may have one or multiple CDRs depending on the call flow, the used PBX objects and their configuration.


It is strongly recommended that you try to precalculate your required disk space and configure a suiting value under [[#Configure_scheduled_CDR_cleanup]]. 
Don't forget to configure the alarm server under [[Reference10:Concept_Linux_Application_Platform#Alarm_Server]] to receive an alarm if the disk is nearly full (10% disk space remaining).


==Installation==

Download the latest version of innovaphone reporting.

Log into the application platform, go to the Applications tag, click on [[ Reference10:Concept_Linux_Application_Platform#Upload.2FUpdate|Upload/Update]] and upload the downloaded file.
The installation will start automatically and the page will refresh every two seconds showing the installation process.
If there is no error during the installation you will see at the end "Installation was succesfull". Otherwise,
you will get "installation failed" and the reason why it went wrong.

===Hotfix===
If you have already installed the latest version of Reporting, simply download the Reporting...HotfixIncremental for your platform (VM or IPxx10) or if you have missed some hotfixes, download the Reporting...HotfixCumulative archive, which contains all hotfixes since hotfix1.
 
 
Upload this hotfix archive [[Reference10:Concept_Linux_Application_Platform#Upload.2FUpdate|here]].

==Configuration==
===Device===

====License====
It is required to have a Reporting license installed on your device. Check under [[ Reference10:General/License ]] if you already have one.

Set the Reporting flag for each PBX object, which should be reported on the objects properties page.

====CDR Gateway====
Any innovaphone device which sends [[Reference10:Concept_Call_Detail_Record_CDR_PBX|CDRs]] to the reporting application must have at least one CDR interface configured under [[ Reference10:Gateway/CDR ]]:

* Type: LOCAL-AP or REMOTE-AP/REMOTE-AP-S

If HTTP/HTTPS is selected then some other parameters must be set:

* Address: ip address of the application platform
* Port: 80 for REMOTE-AP
* Port: 443 for REMOTE-AP-S
* Method: POST/GET
* Path: ap/cdr.fcgi

The application platform is by default password protected, so you'll have to perform one of these steps: 

* configure an authenticated URL for '''ap/cdr.fcgi''' under [[ Reference10:Services/HTTP/Client ]] (recommended)
** If you configure an authenticated URL (with the linux webserver credentials), don't forget to configure port 80 or port 443 for secure transport (Remote-AP-S) like https://111.111.111.111:443/ap or http://111.111.111.111:80/ap
* configure '''ap/cdr.fcgi''' as public web path on the innovaphone application platform [[ Reference10:Concept_Linux_Application_Platform#Change_web_server_properties_and_public_access_to_the_web.2Fwebdav|Public Web Paths ]]

Configure a second CDR interface, if you use [[#Replication|Replication]].

====Enable PBX CDRs====
Enable the "Generate CDRs" flag under [[ Reference10:PBX/Config/General ]].

===innovaphone Application Platform===

If the reporting URL/user/password is not configured in your device as authenticated URL, configure '''ap/cdr.fcgi''' as public web path on the innovaphone application platform [[ Reference10:Concept_Linux_Application_Platform#Change_web_server_properties_and_public_access_to_the_web.2Fwebdav|Public Web Paths ]].

===Database===

Reporting creates the innovaphone-reporting database to store CDRs sent from any innovaphone devices (appendix 7.6 explains the database structure).
PostgreSQL is also available for other applications and any of them could create its own database.

====Password====

Reporting creates the database user '''innovaphone-reporting''' with default password '''reporting'''.
This password may be changed at the innovaphone Reporting page under Config/Database.

====Remote Access====

There are tools (PgAdmin III) that allow to connect to application databases remotely.
It is first needed to configure the IP you are connecting from under Config/Database at the innovaphone reporting page.

For the PgAdmin III it is imporant to use innovaphone-reporting as Service-DB (Wartungs-DB). Default login credentials - User: innovaphone-reporting - Password: reporting

====Delete CDRs====

You can delete CDRs for certain/all users in a certain timespan. If you enter '''%''' as object, all users are selected.

Note that PostgreSQL doesn't free the space on the disk! If you need free disk space, issue this command on the shell:
''sudo -u postgres vacuumdb -f innovaphone-reporting''
This may take some time and CDRs won't be received during this time.

====Configure scheduled CDR cleanup====

If you activate scheduled cleanup, CDRs older than the configured amount of months will be automatically deleted. 
The scheduled task is started once a day at 2 AM.

===PBX===

If you use multiple PBX devices which are not Master/Slave, you have to select, which identifier is unique for a user under Config/PBX:
* System Name (default)
* PBX Name

The selected value determines, which values are shown in the PBX dropdown box for report creation or report mail configuration.

===Replication===

You can configure a second innovaphone application platform with an installed innovaphone Reporting for replication purposes. 

* Mode:
** '''Off''': no replication
** '''Master''': the local server is the master server
** '''Standby''': the local server is the standby server, filters will be replicated from the master and can't be changed here
* Master/Standby Server: the IP address of the master or standby server
* Database password: the PostgreSQL database password of the other server (default is '''reporting''').
* Synchronisation interval: the interval in minutes (range 1-60) in which a sync is done

Now configure a second [[#CDR_Gateway|CDR Gateway]] for the standby server.

The current status can be seen here too. If the status is '''Failed''' take a look at the log file '''innovaphone Reporting Replication''' under [[ Reference10:Concept_Linux_Application_Platform#Logs|Diagnostics/Logs]] or look at the last trace output at the bottom of the page.
 
 
How replication works is described [[#Replication_2|here]].

===LDAP===

Several LDAP servers and dialing locations can be configured here. 

PBX field must correspond to a name of a PBX since PBX's names are available in CDRs. The received CDR is parsed to get the PBX name and this name will be used to find the corresponding LDAP server and dialing location needed to resolve names.

Each configured LDAP server and dialing location can be activated/deactivated with the '''active''' flag.

[[Image:ldap_update.png]]

If the country where you configure LDAP does not have Trunk/National prefix you should leave "National Prefix" and "Area Code" empty.

In the number Attributes field please do '''not''' add any additional characters to the attributes like ":P", ":D" or "@", for instance "homePhone:P, mobile:M, telephoneNumber:D". This does not work. That would be correct: "homePhone, mobile, telephoneNumber"

LDAP Internal Search flag allows reporting to perform name resolution also for internal numbers.

===Report Mails===

Automatic report generation can be configured here:

* '''time''': daytime at which the report is sent
* '''user reports''':
** Creates for each matching user a separate report
** Users are matched by '''Object (Long Name)'''
** A user report only contains calls for this user
** The email address of the user is built by its '''H323 name''' and the '''System Name''' of its PBX (h323@systemname) or determined by the E-Mail field of the user
* '''interval''':
** daily: Mail will be send daily with the automatic period "last day"
** weekly: Mail will be send weekly with the automatic period "last week"
** monthly: Mail will be send daily with the automatic period "last month"
* '''day''': the day, at which the report is sent
* '''mail adresses''': recipients of the report (comma separated)
* '''Sender E-Mail address''': sender email address, which may be present as [[ Reference10:Concept_Linux_Application_Platform#Relay_Hosts | relay host ]]
* '''compress''': compress the attachment or not
* '''sort by'''
* '''sort order'''
* '''language'''
* '''send time''': the time of a day, when the report is sent

The explanation for the other settings can be found [[ #Report_Creation | here. ]] 

[[Image:mails.png]]

===Users===

You can configure multiple users, who shall have access to reports without having access to the whole reporting configuration. 
The user can login with his user name and password on: 

http(s)://Linux-IP/apps/innovaphone-reporting/user/login.php

The admin can assign one or more base filters to the user. A base filter is explained [[ #Base_filter | here]]. 
If the user creates new reports, new own filters or report mails, he '''has''' to use one of his assigned base filters.

If you are using multiple PBX systems, the user has only access to these systems, which are configured in the base filters of the user.
If the user has no base filter with a limitation to a certain "System Name"/"PBX Name" (depends on your [[ #PBX | PBX configuration ]]),
he will have access to all systems!

[[Image:users.jpg]]

====User Login====

A logged in user can create reports, own filters and report mails based on his assigned base filters.

[[Image:Userlogin.jpg]]

===Images===

You may upload images to be used as logo or footer in pdf reports. 

Logos must be 32x32 and footer can have a maximum width of 450 pixels and a maximum height of 50 pixels. 

These images can have jpeg or png format. 

===Relay CDRs===

Relay CDRs can be stored in log files by the Reporting application. Configure a CDR gateway as already described and relay CDRs will be written to the webdav file '''/cdr/cdr.txt'''.
The file is rotated on 1 MB size. The first rotated file is uncompressed, further files will be gz compressed. Max ten files are kept. Older files will be deleted: 
* cdr.txt
* cdr.txt.1
* cdr.txt.2.gz
* cdr.txt.3.gz
* cdr.txt.4.gz
* cdr.txt.5.gz
* cdr.txt.6.gz
* cdr.txt.7.gz
* cdr.txt.8.gz
* cdr.txt.9.gz

===innovaphone-reporting web access===

You can configure a separate authentication for the innovaphone-reporting web site [[Reference10:Concept_Linux_Application_Platform#Change_application_access_credentials|here]]. 
One can just login on the reporting site with this access.

===Integration Voice recorder===

The innovaphone voice recording can be integrated and a remote control of the player is possible, see relative article.

==Filters==
===General===

Filters are set up to create reports based on certain conditions. A filter can have multiple conditions and multiple filters can be combined on report creation (combine is performed with an '''OR'''). 
A filter has a unique '''name''' with an optional '''description'''.

===Conditions===

[[Image:filter.png]]

There are five or seven condition sections depending on what is selected under '''States'''. Conditions inside same section are '''OR''' associated while different sections are '''AND''' associated.
 

(Object == Terra '''OR''' Object == Uranus) '''AND''' (PBX == sifi) '''AND''' (Number == 0049%)

====Base filter====

If you select another filter as base filter, the conditions of the base filter are implicitly '''AND''' conjuncted, when the current filter is used. 
So if the base filter defines two PBX values, e.g. "Berlin" and "Hamburg" and the current filter defines one PBX value, e.g. "Berlin", only objects of the PBX "Berlin" will be filtered: 

(pbx="Berlin") AND (pbx="Berlin" OR pbx="Hamburg")

If a user defines an own filter for his reports, he has to use a base filter, which he is allowed to use. So each filter, which he uses, will have at least one base filter condition, which the admin has defined.

You have to take care with the conditions of the current filter and the base filter,
as it is now easy to create a filter with mutually exclusive conditions, e.g. if
the filter has pbx="Berlin" and the base filter pbx="Hamburg" => no matching records.

====Anonym====

If you check this flag, a report created with this filter or with a filter, where this filter is a basefilter, will by anonymized.

====Local====

Define one ore more conditions for the local party, defined by:

* Object: the cn/PBX object name
* Number: the number
* Groups: a group of the PBX object

====Remote====

Define one or more conditions for the remote party, defined by:

* Number: the number
* Remote display name: the display name

====PBX====

Define one ore more conditions for the PBX, defined by:

* PBX: the PBX name
* Node: the node name

====States====

* No Response
* Connected
* Busy
* No Channel

====Directions====

* Incoming
* Outgoing
* Transfer: calls, which have been transferred to the current local party
* Call Forward: calls, which have been forwarded to the current local party

====Call Duration====

Time the call was connected.

This condition will be '''AND''' with the others if all '''States''' are selected. 
If Busy, No Channel or No Response is unselected, then the filter will search for Connected calls with connected time greater or smaller than '''Call Duration'''.

====Alert Duration====

Time the call was ringing independent of the status of the call afterwards.

This condition will be '''AND''' with the others if all '''States''' are selected. 
If Busy, No Channel or Connected is unselected, then the filter will search only for Not Connected Calls that were ringing more or less time than '''Alert Duration'''.

====Report times====

Define the time where calls should be counted. 
You can optionally define the weekday(s) of calls.

====Images====

* Logo: This must be 32x32 pixel image in jpeg or png format. 
* Footer: Maximum width of 450 pels and maximum height of 50 pels. Also jpeg or png format. 

====Using Patterns====

You can use these [[ #PostgreSQL_Patterns | PostgreSQL Patterns ]] for every condition.

==Report Creation==
===General===

It is possible to generate call lists for single users or more complex reports by means of filters.

===Web Interface===

Reporting application provides a web interface to generate reports.

[[Image:Report_hide.png]]

* '''PBX''': select the PBX for the report. The values of the drop down box depend on your [[#PBX | PBX configuration]]
* '''Object (Long Name)''': corresponds to the PBX Long Name assigned to a specific user (% is a special postgresql character, which matches any string)
* '''Filter''': one or multiple filters can be defined ('''OR''' joined)
* '''Group by''': the result can be grouped by Date or Object
* '''Hide last X digits''': you may replace the last digits of an external number with a '*'.
** LDAP must be configured in order to use this capability but if you want no LDAP funtionality, just unset the Active Box in LDAP.
** Actually, the pbx/phys value of a call is matched against the LDAP pbx value and if the number starts with the external line prefix.
* '''Anonym''': do not show internal names/numbers
** If anonym is set, hide last digits is set to 3, if not set
* '''Filter Info''': the report will contain information about the configured settings and filter information
* '''Displayed Duration''':
** Call Duration (Total): the total call duration, e.g. with the duration of a subsequent transfer
** Call Duration (User): just the time, the user was connected
** Billing Duration: the duration, a user must be billed for
** None of these durations contain the alert duration, which is separatly listed

[[Image:reporting_report.png | A normal report. The summary shows incoming / outgoing summaries]]

[[Image:grouped_report.png | A grouped report. Each group has an own summary]]

====Print====

Click the print icon to open a printable version of the report.

====Save====
You can save the report as '''pdf''' or as '''xml''' by using the corresponding icon. 
You can also download a report in '''csv''' format without call history. The report uses '''comma''' as delimeter character, '''"''' as text qualifier and '''PBX Object/Remote Party''' columns should be defined as Text (avoid telephone numbers to be considered as numbers by Excel). '''UTF-8''' must be used as character set. 

====Sorting====

Each sortable column has a clickable column head. This sorting will be also used when opening the printable version or saving the report as PDF.

====Icons====
The icons are explained in the [[#Call list icons|appendix]].

===Remote Interface===

See [[#Remote_Interface_2|Remote Interface Appendix]]

==Backup and Restore==

You can both manually and automatically backup the database and configuration files for Reporting under [[Reference10:Concept_Linux_Application_Platform#Backup|Administration/Backup]] in the application platform.

Configuration details for the update server can be found [[Reference10:Concept_Linux_Application_Platform#Backup|here]].

===Configuration Files===

'''saveinnovaphone-reportingcfgs''' is the command used to automatically save configuration files with the [[Reference10:Concept_Linux_Application_Platform#Command_File|Command File]].

===Data===

'''saveinnovaphone-reportingdb''' is the command to automatically backup the whole innovaphone Reporting database with the [[Reference10:Concept_Linux_Application_Platform#Command_File|Command File]].

If you restore the reporting database, you should keep in mind, that this might take several hours for a system
on a CF card, depending on the size of the restored database. The backup process itself is quite fast with a few minutes.

===Logs===

'''saveinnovaphone-reportinglogs''' to save log files with the [[Reference10:Concept_Linux_Application_Platform#Command_File|Command File]].

==Appendix==
===PostgreSQL Patterns===
For filter conditions or for the pbx object value you can use the following patterns inside a string:

* '''%''': matches any string of zero or more characters
* '''_''': matches any single character

Example:
'''Sat%''' will match all pbx objects, which start with the string '''Sat'''.

We do always perform case insensitiv searches!

===innovaphone Reporting XML===
<code type="xml">
<?xml version="1.0" encoding="utf-8"?>
<application>
<name>innovaphone Reporting</name>
<desc>Reporting software</desc>
<directory>innovaphone-reporting</directory>
<href>report.php</href>
<linux-username>innovaphone-reporting</linux-username>
<packages>
<package>php5-gd</package>
<package>php5-ldap</package>
</packages>
<database name="innovaphone-reporting" username="innovaphone-reporting"/>
<cronjobs>
<cronjob script="/etc/cron.d/reporting_replication"/>
<cronjob script="/etc/cron.d/reporting_cleanup"/>
<cronjob script="/etc/cron.d/reporting_mails"/>
</cronjobs>
<log-files>
<log title="Postgresql-8.4" no-clear="true">/var/log/postgresql/postgresql-8.4-main.log</log>
<log title="Reporting cleanup">/var/www/innovaphone/apps/innovaphone-reporting/log/reporting_cleanup.log</log>
<log title="innovaphone Reporting">/var/www/innovaphone/apps/innovaphone-reporting/log/innovaphone-reporting.log</log>
<log title="innovaphone Reporting Replication">/var/www/innovaphone/apps/innovaphone-reporting/log/reporting_replication.log</log>
</log-files>
<config-files>
<conf>/etc/postgresql/8.4/main/pg_hba.conf</conf>
<conf>/etc/postgresql/8.4/main/postgresql.conf</conf>
<conf>/home/innovaphone-reporting/reporting.conf</conf>
<conf>/home/root/ssl_cert/server.key</conf>
<conf>/home/root/ssl_cert/server.crt</conf>
<conf>/etc/cron.d/reporting_replication</conf>
<conf>/etc/cron.d/reporting_cleanup</conf>
<conf>/etc/cron.d/reporting_mails</conf>
<conf>/var/www/innovaphone/apps/innovaphone-reporting/report_images</conf>
</config-files>
<backup>
<command title="Save innovaphone Reporting configuration files" cmd="saveinnovaphone-reportingcfgs" script=""/>
<command title="Save innovaphone Reporting database" cmd="saveinnovaphone-reportingdb" script=""/>
<command title="Save innovaphone Reporting log files" cmd="saveinnovaphone-reportinglogs" script=""/>
</backup>
<restore>
<command title="Restore innovaphone Reporting configuration files" cmd="restoreinnovaphone-reportingcfgs" script="">
<action>/etc/init.d/postgresql restart</action>
<action>/etc/init.d/cron restart</action>
</command>
<command title="Restore innovaphone Reporting database" cmd="restoreinnovaphone-reportingdb" script=""/>
</restore>
<uninstall script="/usr/bin/sudo /usr/local/bin/uninstall_script.sh -f 'innovaphone-reporting.xml' -linux_user yes -linux_group yes -database yes -database_user yes -log_script '/var/www/innovaphone/log/appl_uninstall.log'">
<to-delete>
<to-del path="/usr/local/bin/reporting_cleanup.sh"/>
<to-del path="/usr/local/bin/reporting_replication.out"/>
<to-del path="/usr/local/bin/reporting_replication.sh"/>
<to-del path="/home/innovaphone-reporting/tmp"/>
</to-delete>
</uninstall>
<lighttpd-auth>1</lighttpd-auth>
<public-web-paths>
<path>mypbx</path>
<path>user</path>
</public-web-paths>
</code>

===Installed Debian Packages===

The following packages (and their dependencies) are installed with innovaphone Reporting:

* php5-gd
* php5-ldap

===Configuration Files===

pg_hba.conf is the client authentication configuration file and controls which hosts are allowed to connect, how clients
are authenticated, which PostgreSQL user names they can use and which databases they can access.

postgresql.conf is the PostgreSQL configuration file

===Data Files===

If you backup the innovaphone reporting database, you'll get a gz archiv, which contains the whole innovaphone-reporting database.

===Report XML===
The node description also applies for the '''CSV''' columns!

<code type="xml">
<report>
<record>
....
<time time="1301303966" utc="1301303966">2011-03-28 11:19:26</time>
<obj>Saturn</obj>
<id>870998fee909d311b2ec009033105dc9</id>
<call>int</call>
<alert-duration seconds="0">0:00</alert-duration>
<flow>
<ev caller="ep1" ep1_number="101" ep1_name="saturn" ep1_dn="Saturn"
ep2_number="102" ep2_name="uranus" ep2_dn="Uranus" status="co" entry="true"/>
</flow>
<call-duration seconds="2">0:02</call-duration>
<billing-duration seconds="2">0:02</billing-duration>
<conn-duration seconds="2">0:02</conn-duration>
<groups>
<group>test</group>
<group>test2</group>
</groups>
<node>root</node>
<pbx>.</pbx>
<cause></cause>
<dir>o</dir>
<status>co</status>
<type/>
<remote number="102" name="uranus" dn="Uranus"/>
<callback number="456" name="abc" dn="123" time="1301305962">2011-03-28 11:52:42</callback>
</record>
....
</report>
</code>

* time: the node contains a formatted time string of the local time
** attribute '''time''' is a unix timestamp (referring to the local time stamp of the CDR)
** attribute '''utc''' is a unix timestamp (referring to the utc time stamp of the CDR)
* obj: the PBX object name (also called cn)
* id: the conference id of the call
* call: '''int''' (internal) or '''ext''' (external) call
* flow '''(XML only)''': the call flow
** ev
***ep1 (ep1_number, ep1_name, ep1_dn): the left side of the call
***ep2 (ep2_number, ep2_name, ep2_dn): the right side of the call
***caller: '''ep1''', '''ep2''' or empty, if unknown
***status: '''co''' (connected), '''al''' (alert), '''er''' (error) or '''bu''' (busy) state of the current event
***entry: '''true''' for the entry event of the local object
***type: '''cf''' (call forward), '''ct''' (call transfer)
* Original Called '''(CSV only)''': In case of Call flow; The original called device
* Diverting '''(CSV only)''': In case of Call flow; The diverting device
* Transferring '''(CSV only)''': In case of Call flow; The transferring device
* groups '''(XML only)''': the groups of the PBX object
* node: the node of the PBX object
* pbx: the pbx of the PBX object
* cause: the decimal disconnect reason of the call (see [[Reference:ISDN_Cause_Codes]])
* remote:
** outgoing calls -> dialed endpoint
** incoming calls -> first ep2 above entry event or entry event if this is the first one
** incoming calls with incoming transfer after entry event -> transfer target
* status:
** outgoing calls -> best found status in call flow
** incoming calls -> status of entry event
* type: the type of the entry event or, if not set, the type of the next event, if given
** empty: direct call
** '''ct''': call transfer
** '''cf''': call forward
** '''cct''': call transfer with consultation
** '''pu''': call pickup
* dir: o (outgoing) if the first event is the entry event and the caller is ep1
* dir: i (incoming) if not o
* alert-duration: alert time
* billing-duration: outgoing call -> duration from the first event until the last event in the flow
* billing-duration: incoming call -> duration from the first transfer/forward event until the last event in the flow
* call-duration: duration of the whole call
* conn-duration: duration from the entry event until the event, where the local endpoint isn't connected any more
* callback: '''name''', '''number''', '''dn''' and '''time''' if this call has been callbacked using mypbx (time referrs to the UTC time of the callback)
* Further Registration: If more than one devices is registered to the same object, each device creates a CDR. This field identifies the additional CDRs for the same call
* Object Info '''(CSV only)''': combination of object names and number
* Date '''(CSV only)''': extracted date only from the time_string
* Time_2 '''(CSV only)''': extracted time only from the time_string

===Database Structure===

====cdrs====
Each received cdr-xml is formed by a cdr tag and an undefined number of event and group tags.
(Refer to: [[Reference10:Concept_Call_Detail_Record_CDR_PBX|CDR]])

This section is composed by four tables: cdrs, events, groups and cdr_properties.
The first three tables contain the corresponding fields to store the information contained in the cdr, event and group tags. 
Each CDR represents the call in the view of one PBX object. So there might be multiple CDRs for one call if multiple PBX objects are used within the call.

* '''cdr fields:''' id, guid, sys, pbx, node, device, cn, e164, h323, dir, utc, local.
* '''event fields:''' id, msg, type, e164, h323, conf, cause, time, cdr_id, order_index.
* '''group fields:''' id, name, active, type, cdr_id.

'''id''' field is assigned by postgresql for each entry and has nothing to do with the information present in the cdr. It is different for each entry inside the table.

The events table has two additional fields, called cdr_id, to associate these events to the corresponding cdr entry and order_index to keep their position inside the cdr.
Groups table has also the cdr_id field to associate the group entries to the corresponding cdr and events entries.

The '''cdr_properties''' table contains relevant information associated with the call such as call_length, alert_length or call_flow. It also presents a cdr_id field.

====filters====

This section is composed by three tables: filter_columns, filter_conditions and filters.

* '''filter_columns''' is not used for the time being. This is supposed to contain the columns the user wants to see in his report, but right now, just default columns (Time/Object/Duration/Left/Direction/State/Right) are shown.
* '''filter''' contains the filter name and description plus two conditions call_state (No Response, Connected, Busy and No Channel) and direction (Incoming, Outgoing, Transfer and Call Forward).
* '''filter_conditions''' contains the defined conditions for a filter

All three tables are related through an id.

====cdr_users====

This table contains a timestamp '''missed_calls_time''' for the last report access by a user '''cn''' + ('''pbx''' OR '''sys''') with mypbx. It is used to retrieve information about missed calls since the last use of mypbx. 
The timestamp '''clear_report_time''' indicates the last clearance time. 
email, sys (system name) and pbx (PBX name) are also stored for each user.

====replication====

Contains information of the last replication run, which is used to sync master/standby installations.

===Replication===

The replication between the master and standby servers is divided into two steps:

====CDRs====
Both master and standby server keep an information about the last replicated CDR. From this CDR on, they retrieve all CDR guids (32 bytes) from all new CDRs from the other server. If a guid already exists in the local database, the CDR is skipped, otherwise it is replicated. 
So there is a minimal data exchange for already existing CDRs and each new CDR is only processed once.

====Filters/LDAP/Report Mails/Users====
The master server does nothing here, but the '''standby''' deletes all filters, LDAP servers, report mails and users and replicates all from the master. 
So these items from the master server can be used, but not changed, on the standby server.

===Remote Interface===

You can retrieve the PDF/XML/CSV report with a remote interface. 
Make a POST or GET HTTP request to '''http(s)://Linux-IP/apps/innovaphone-reporting/report.php''' with the following parameters:

* remote: mandatory for a remote request!
** '''1'''
* from : the from date/time as UNIX timestamp '''OR''' date/time string as described [ http://www.php.net/manual/de/datetime.formats.php | here ].
* to: the to date/time (format see '''from''')
* [format]: the return format, allowed values:
** '''xml''': default
** '''pdf'''
** '''csv'''
* [sortby] : the report sorting, allowed values:
** '''time''': default
** '''obj''': sort by pbx object name
** '''call-duration'''
** '''alert-duration'''
** '''dir''': sort by call direction
* [sortorder]: the report sort order, allowed values:
** '''ascending''': default
** '''descending'''
* [groupby]: report grouping
** default empty/not set: no grouping
** '''local_stamp''': group by time
** '''cn''': group by pbx object name
* [hidedigits]: hide the last X digits of external numbers
* pbx: search for this PBX (mandatory!)
* pbxobject: search for this PBX object (you can leave this, if you use filterX)
* filterX: use a filter with its name. You can use multiple filters with filter1=test, filter2=test2...
* [filterinfo]: show the filter information in a created report ("true" or "false")
* [lang]: the language, e.g. "en" or "de"
* [displayedduration]:
** '''call_duration''': default Call Duration (Total)
** '''conn_duration''': Call Duration (User)
** '''billing_duration''': Billing Duration
* [anonym]: anonymize internal names/numbers ("true" or "false")
* [bulk]: creates user reports (see [[ #Report_Mails | Report Mails ]])
* [sender]: sender email adress of the report
* [confid]: query calls of a certain conference ID
** you can omit the following fields, if using confid: '''from''', '''to''', '''pbx''', '''pbxobject''', '''filterX'''

Parameters in [] are optional.

'''pbxobject''' supports [[ #PostgreSQL_Patterns | PostgreSQL Patterns ]].

Example:
https://172.16.14.123/apps/innovaphone-reporting/report.php?remote=1&from=2011-03-29&to=2011-03-30&format=xml&pbxobject=Saturn
Gets all records between 2011-03-29 and 2011-03-30 for the pbx object Saturn.

Example:
https://172.16.14.123/apps/innovaphone-reporting/report.php?remote=1&from=2011-03-29&to=2011-03-30&format=xml&filter1=test&filter2=test2
Gets all records between 2011-03-29 and 2011-03-30 for the filters test and test2.

===Tools===

====NetDrive====

[http://www.heise.de/software/download/netdrive/55134 NetDrive] is a usefull webdav client, which can be used to access webdav of the innovaphone application platform.

====PGAdmin====

[http://www.pgadmin.org/ PGAdmin] is an administration tool for PostgreSQL databases.

====Putty====

[http://www.putty.org/ Putty] is SSH client to connect to the linux application platform.

===Call list icons===
The direction of the icon arrow depends on the call flow.

* [[Image:reporting_conn.jpg]]: a connected call
* [[Image:reporting_busy.jpg]]: busy destination
* [[Image:reporting_no_res.jpg]]: no response from destination
* [[Image:reporting_error.jpg]]: an error occurred, like "no channel available" during the call setup
* [[Image:reporting_ct.jpg]]: call transfer
* [[Image:reporting_cct.jpg]]: call transfer with consultation
* [[Image:reporting_cf.jpg]]: call forward
* [[Image:Reporting_pickup.jpg]]: call pickup (or SOAP redirect)
* [[Image:reporting_dir.jpg]]: call direction

A small arrow on a call state icon indicates a callback done with mxPBY, e.g.:
* [[Image:reporting_busy_callback.jpg]]

==Known Problems==
===Replication===
====Callback information====
The callback information get lost in the following scenario:
* The callback CDR is already replicated on both master and standby
* Master or standby is down
* A user calls back the CDR from point 1

====Missed calls====
The information for missed calls is not replicated. So the first time, a standby server is used with mypbx, the missed calls information will be wrong. The second time will be correct again.

===CDRs===
If the innovaphone Reporting is not running, for whatever reaseon, the device, which sends CDRs, currently stores up to 300kB CDRs data. So if one CDR has up to 2kB, 150 CDRs can be stored until the innovaphone Reporting should be up again, to avoid data loss.

===Missing values for PBX drop down box===
If your database currently contains no CDRs of one of your PBX systems, you won't be able to select this system as PBX for report creation or report mail configuration!

===Restoring Database with more than 2GB===

When restoring database using the web browser there is a 2GB upload limit, so if our database have a bigger size the upload will fail.

As alternative solution (if there is enough space):

1. Copy the gz database dump to the webdav folder
2. Uncompress this dump: /bin/gzip -cd /var/www/innovaphone/webdav/dump.gz --uncompress > /tmp/db.dump
3. Start the restore: /usr/local/bin/config.sh postgres db-restore /tmp/pg_schema.dump /tmp/db.dump innovaphone-reporting
4. be patient, this might take a while
5. delete /tmp/db.dump, /var/www/innovaphone/webdav/dump.gz and /tmp/pg_schema.dump (automatically created)

===PDF generation for many CDRs may fail===
You may experience a '''Server error 500''' if you generate PDFs with many CDRs. The PDF library which is used to generate the PDFs fails.
Please generate multiple PDFs with a smaller timespan in such a case.

== Related Articles ==

[[Howto:Integration_reporting_and_voice_recording]]

[[Category:Concept|Reporting]]

Reference10:Concept Reporting

2016-10-17T09:42:06Z

Tru: /* Remote Interface */

==Requirements==

It is needed to have the [[Reference10:Concept_Linux_Application_Platform|application platform]] installed and running.

===Calculation of required disk space===

An average CDR requires 2080 bytes of disk space inside the database. 
So '''one GB''' disk space is needed for ~'''516222 CDRs'''. 
One call may have one or multiple CDRs depending on the call flow, the used PBX objects and their configuration.


It is strongly recommended that you try to precalculate your required disk space and configure a suiting value under [[#Configure_scheduled_CDR_cleanup]]. 
Don't forget to configure the alarm server under [[Reference10:Concept_Linux_Application_Platform#Alarm_Server]] to receive an alarm if the disk is nearly full (10% disk space remaining).


==Installation==

Download the latest version of innovaphone reporting.

Log into the application platform, go to the Applications tag, click on [[ Reference10:Concept_Linux_Application_Platform#Upload.2FUpdate|Upload/Update]] and upload the downloaded file.
The installation will start automatically and the page will refresh every two seconds showing the installation process.
If there is no error during the installation you will see at the end "Installation was succesfull". Otherwise,
you will get "installation failed" and the reason why it went wrong.

===Hotfix===
If you have already installed the latest version of Reporting, simply download the Reporting...HotfixIncremental for your platform (VM or IPxx10) or if you have missed some hotfixes, download the Reporting...HotfixCumulative archive, which contains all hotfixes since hotfix1.
 
 
Upload this hotfix archive [[Reference10:Concept_Linux_Application_Platform#Upload.2FUpdate|here]].

==Configuration==
===Device===

====License====
It is required to have a Reporting license installed on your device. Check under [[ Reference10:General/License ]] if you already have one.

Set the Reporting flag for each PBX object, which should be reported on the objects properties page.

====CDR Gateway====
Any innovaphone device which sends [[Reference10:Concept_Call_Detail_Record_CDR_PBX|CDRs]] to the reporting application must have at least one CDR interface configured under [[ Reference10:Gateway/CDR ]]:

* Type: LOCAL-AP or REMOTE-AP/REMOTE-AP-S

If HTTP/HTTPS is selected then some other parameters must be set:

* Address: ip address of the application platform
* Port: 80 for REMOTE-AP
* Port: 443 for REMOTE-AP-S
* Method: POST/GET
* Path: ap/cdr.fcgi

The application platform is by default password protected, so you'll have to perform one of these steps: 

* configure an authenticated URL for '''ap/cdr.fcgi''' under [[ Reference10:Services/HTTP/Client ]] (recommended)
** If you configure an authenticated URL (with the linux webserver credentials), don't forget to configure port 80 or port 443 for secure transport (Remote-AP-S) like https://111.111.111.111:443/ap or http://111.111.111.111:80/ap
* configure '''ap/cdr.fcgi''' as public web path on the innovaphone application platform [[ Reference10:Concept_Linux_Application_Platform#Change_web_server_properties_and_public_access_to_the_web.2Fwebdav|Public Web Paths ]]

Configure a second CDR interface, if you use [[#Replication|Replication]].

====Enable PBX CDRs====
Enable the "Generate CDRs" flag under [[ Reference10:PBX/Config/General ]].

===innovaphone Application Platform===

If the reporting URL/user/password is not configured in your device as authenticated URL, configure '''ap/cdr.fcgi''' as public web path on the innovaphone application platform [[ Reference10:Concept_Linux_Application_Platform#Change_web_server_properties_and_public_access_to_the_web.2Fwebdav|Public Web Paths ]].

===Database===

Reporting creates the innovaphone-reporting database to store CDRs sent from any innovaphone devices (appendix 7.6 explains the database structure).
PostgreSQL is also available for other applications and any of them could create its own database.

====Password====

Reporting creates the database user '''innovaphone-reporting''' with default password '''reporting'''.
This password may be changed at the innovaphone Reporting page under Config/Database.

====Remote Access====

There are tools (PgAdmin III) that allow to connect to application databases remotely.
It is first needed to configure the IP you are connecting from under Config/Database at the innovaphone reporting page.

For the PgAdmin III it is imporant to use innovaphone-reporting as Service-DB (Wartungs-DB). Default login credentials - User: innovaphone-reporting - Password: reporting

====Delete CDRs====

You can delete CDRs for certain/all users in a certain timespan. If you enter '''%''' as object, all users are selected.

Note that PostgreSQL doesn't free the space on the disk! If you need free disk space, issue this command on the shell:
''sudo -u postgres vacuumdb -f innovaphone-reporting''
This may take some time and CDRs won't be received during this time.

====Configure scheduled CDR cleanup====

If you activate scheduled cleanup, CDRs older than the configured amount of months will be automatically deleted. 
The scheduled task is started once a day at 2 AM.

===PBX===

If you use multiple PBX devices which are not Master/Slave, you have to select, which identifier is unique for a user under Config/PBX:
* System Name (default)
* PBX Name

The selected value determines, which values are shown in the PBX dropdown box for report creation or report mail configuration.

===Replication===

You can configure a second innovaphone application platform with an installed innovaphone Reporting for replication purposes. 

* Mode:
** '''Off''': no replication
** '''Master''': the local server is the master server
** '''Standby''': the local server is the standby server, filters will be replicated from the master and can't be changed here
* Master/Standby Server: the IP address of the master or standby server
* Database password: the PostgreSQL database password of the other server (default is '''reporting''').
* Synchronisation interval: the interval in minutes (range 1-60) in which a sync is done

Now configure a second [[#CDR_Gateway|CDR Gateway]] for the standby server.

The current status can be seen here too. If the status is '''Failed''' take a look at the log file '''innovaphone Reporting Replication''' under [[ Reference10:Concept_Linux_Application_Platform#Logs|Diagnostics/Logs]] or look at the last trace output at the bottom of the page.
 
 
How replication works is described [[#Replication_2|here]].

===LDAP===

Several LDAP servers and dialing locations can be configured here. 

PBX field must correspond to a name of a PBX since PBX's names are available in CDRs. The received CDR is parsed to get the PBX name and this name will be used to find the corresponding LDAP server and dialing location needed to resolve names.

Each configured LDAP server and dialing location can be activated/deactivated with the '''active''' flag.

[[Image:ldap_update.png]]

If the country where you configure LDAP does not have Trunk/National prefix you should leave "National Prefix" and "Area Code" empty.

In the number Attributes field please do '''not''' add any additional characters to the attributes like ":P", ":D" or "@", for instance "homePhone:P, mobile:M, telephoneNumber:D". This does not work. That would be correct: "homePhone, mobile, telephoneNumber"

LDAP Internal Search flag allows reporting to perform name resolution also for internal numbers.

===Report Mails===

Automatic report generation can be configured here:

* '''time''': daytime at which the report is sent
* '''user reports''':
** Creates for each matching user a separate report
** Users are matched by '''Object (Long Name)'''
** A user report only contains calls for this user
** The email address of the user is built by its '''H323 name''' and the '''System Name''' of its PBX (h323@systemname) or determined by the E-Mail field of the user
* '''interval''':
** daily: Mail will be send daily with the automatic period "last day"
** weekly: Mail will be send weekly with the automatic period "last week"
** monthly: Mail will be send daily with the automatic period "last month"
* '''day''': the day, at which the report is sent
* '''mail adresses''': recipients of the report (comma separated)
* '''Sender E-Mail address''': sender email address, which may be present as [[ Reference10:Concept_Linux_Application_Platform#Relay_Hosts | relay host ]]
* '''compress''': compress the attachment or not
* '''sort by'''
* '''sort order'''
* '''language'''
* '''send time''': the time of a day, when the report is sent

The explanation for the other settings can be found [[ #Report_Creation | here. ]] 

[[Image:mails.png]]

===Users===

You can configure multiple users, who shall have access to reports without having access to the whole reporting configuration. 
The user can login with his user name and password on: 

http(s)://Linux-IP/apps/innovaphone-reporting/user/login.php

The admin can assign one or more base filters to the user. A base filter is explained [[ #Base_filter | here]]. 
If the user creates new reports, new own filters or report mails, he '''has''' to use one of his assigned base filters.

If you are using multiple PBX systems, the user has only access to these systems, which are configured in the base filters of the user.
If the user has no base filter with a limitation to a certain "System Name"/"PBX Name" (depends on your [[ #PBX | PBX configuration ]]),
he will have access to all systems!

[[Image:users.jpg]]

====User Login====

A logged in user can create reports, own filters and report mails based on his assigned base filters.

[[Image:Userlogin.jpg]]

===Images===

You may upload images to be used as logo or footer in pdf reports. 

Logos must be 32x32 and footer can have a maximum width of 450 pixels and a maximum height of 50 pixels. 

These images can have jpeg or png format. 

===Relay CDRs===

Relay CDRs can be stored in log files by the Reporting application. Configure a CDR gateway as already described and relay CDRs will be written to the webdav file '''/cdr/cdr.txt'''.
The file is rotated on 1 MB size. The first rotated file is uncompressed, further files will be gz compressed. Max ten files are kept. Older files will be deleted: 
* cdr.txt
* cdr.txt.1
* cdr.txt.2.gz
* cdr.txt.3.gz
* cdr.txt.4.gz
* cdr.txt.5.gz
* cdr.txt.6.gz
* cdr.txt.7.gz
* cdr.txt.8.gz
* cdr.txt.9.gz

===innovaphone-reporting web access===

You can configure a separate authentication for the innovaphone-reporting web site [[Reference10:Concept_Linux_Application_Platform#Change_application_access_credentials|here]]. 
One can just login on the reporting site with this access.

===Integration Voice recorder===

The innovaphone voice recording can be integrated and a remote control of the player is possible, see relative article.

==Filters==
===General===

Filters are set up to create reports based on certain conditions. A filter can have multiple conditions and multiple filters can be combined on report creation (combine is performed with an '''OR'''). 
A filter has a unique '''name''' with an optional '''description'''.

===Conditions===

[[Image:filter.png]]

There are five or seven condition sections depending on what is selected under '''States'''. Conditions inside same section are '''OR''' associated while different sections are '''AND''' associated.
 

(Object == Terra '''OR''' Object == Uranus) '''AND''' (PBX == sifi) '''AND''' (Number == 0049%)

====Base filter====

If you select another filter as base filter, the conditions of the base filter are implicitly '''AND''' conjuncted, when the current filter is used. 
So if the base filter defines two PBX values, e.g. "Berlin" and "Hamburg" and the current filter defines one PBX value, e.g. "Berlin", only objects of the PBX "Berlin" will be filtered: 

(pbx="Berlin") AND (pbx="Berlin" OR pbx="Hamburg")

If a user defines an own filter for his reports, he has to use a base filter, which he is allowed to use. So each filter, which he uses, will have at least one base filter condition, which the admin has defined.

You have to take care with the conditions of the current filter and the base filter,
as it is now easy to create a filter with mutually exclusive conditions, e.g. if
the filter has pbx="Berlin" and the base filter pbx="Hamburg" => no matching records.

====Anonym====

If you check this flag, a report created with this filter or with a filter, where this filter is a basefilter, will by anonymized.

====Local====

Define one ore more conditions for the local party, defined by:

* Object: the cn/PBX object name
* Number: the number
* Groups: a group of the PBX object

====Remote====

Define one or more conditions for the remote party, defined by:

* Number: the number
* Remote display name: the display name

====PBX====

Define one ore more conditions for the PBX, defined by:

* PBX: the PBX name
* Node: the node name

====States====

* No Response
* Connected
* Busy
* No Channel

====Directions====

* Incoming
* Outgoing
* Transfer: calls, which have been transferred to the current local party
* Call Forward: calls, which have been forwarded to the current local party

====Call Duration====

Time the call was connected.

This condition will be '''AND''' with the others if all '''States''' are selected. 
If Busy, No Channel or No Response is unselected, then the filter will search for Connected calls with connected time greater or smaller than '''Call Duration'''.

====Alert Duration====

Time the call was ringing independent of the status of the call afterwards.

This condition will be '''AND''' with the others if all '''States''' are selected. 
If Busy, No Channel or Connected is unselected, then the filter will search only for Not Connected Calls that were ringing more or less time than '''Alert Duration'''.

====Report times====

Define the time where calls should be counted. 
You can optionally define the weekday(s) of calls.

====Images====

* Logo: This must be 32x32 pixel image in jpeg or png format. 
* Footer: Maximum width of 450 pels and maximum height of 50 pels. Also jpeg or png format. 

====Using Patterns====

You can use these [[ #PostgreSQL_Patterns | PostgreSQL Patterns ]] for every condition.

==Report Creation==
===General===

It is possible to generate call lists for single users or more complex reports by means of filters.

===Web Interface===

Reporting application provides a web interface to generate reports.

[[Image:Report_hide.png]]

* '''PBX''': select the PBX for the report. The values of the drop down box depend on your [[#PBX | PBX configuration]]
* '''Object (Long Name)''': corresponds to the PBX Long Name assigned to a specific user (% is a special postgresql character, which matches any string)
* '''Filter''': one or multiple filters can be defined ('''OR''' joined)
* '''Group by''': the result can be grouped by Date or Object
* '''Hide last X digits''': you may replace the last digits of an external number with a '*'.
** LDAP must be configured in order to use this capability but if you want no LDAP funtionality, just unset the Active Box in LDAP.
** Actually, the pbx/phys value of a call is matched against the LDAP pbx value and if the number starts with the external line prefix.
* '''Anonym''': do not show internal names/numbers
** If anonym is set, hide last digits is set to 3, if not set
* '''Filter Info''': the report will contain information about the configured settings and filter information
* '''Displayed Duration''':
** Call Duration (Total): the total call duration, e.g. with the duration of a subsequent transfer
** Call Duration (User): just the time, the user was connected
** Billing Duration: the duration, a user must be billed for
** None of these durations contain the alert duration, which is separatly listed

[[Image:reporting_report.png | A normal report. The summary shows incoming / outgoing summaries]]

[[Image:grouped_report.png | A grouped report. Each group has an own summary]]

====Print====

Click the print icon to open a printable version of the report.

====Save====
You can save the report as '''pdf''' or as '''xml''' by using the corresponding icon. 
You can also download a report in '''csv''' format without call history. The report uses '''comma''' as delimeter character, '''"''' as text qualifier and '''PBX Object/Remote Party''' columns should be defined as Text (avoid telephone numbers to be considered as numbers by Excel). '''UTF-8''' must be used as character set. 

====Sorting====

Each sortable column has a clickable column head. This sorting will be also used when opening the printable version or saving the report as PDF.

====Icons====
The icons are explained in the [[#Call list icons|appendix]].

===Remote Interface===

See [[#Remote_Interface_2|Remote Interface Appendix]]

==Backup and Restore==

You can both manually and automatically backup the database and configuration files for Reporting under [[Reference10:Concept_Linux_Application_Platform#Backup|Administration/Backup]] in the application platform.

Configuration details for the update server can be found [[Reference10:Concept_Linux_Application_Platform#Backup|here]].

===Configuration Files===

'''saveinnovaphone-reportingcfgs''' is the command used to automatically save configuration files with the [[Reference10:Concept_Linux_Application_Platform#Command_File|Command File]].

===Data===

'''saveinnovaphone-reportingdb''' is the command to automatically backup the whole innovaphone Reporting database with the [[Reference10:Concept_Linux_Application_Platform#Command_File|Command File]].

If you restore the reporting database, you should keep in mind, that this might take several hours for a system
on a CF card, depending on the size of the restored database. The backup process itself is quite fast with a few minutes.

===Logs===

'''saveinnovaphone-reportinglogs''' to save log files with the [[Reference10:Concept_Linux_Application_Platform#Command_File|Command File]].

==Appendix==
===PostgreSQL Patterns===
For filter conditions or for the pbx object value you can use the following patterns inside a string:

* '''%''': matches any string of zero or more characters
* '''_''': matches any single character

Example:
'''Sat%''' will match all pbx objects, which start with the string '''Sat'''.

We do always perform case insensitiv searches!

===innovaphone Reporting XML===
<code type="xml">
<?xml version="1.0" encoding="utf-8"?>
<application>
<name>innovaphone Reporting</name>
<desc>Reporting software</desc>
<directory>innovaphone-reporting</directory>
<href>report.php</href>
<linux-username>innovaphone-reporting</linux-username>
<packages>
<package>php5-gd</package>
<package>php5-ldap</package>
</packages>
<database name="innovaphone-reporting" username="innovaphone-reporting"/>
<cronjobs>
<cronjob script="/etc/cron.d/reporting_replication"/>
<cronjob script="/etc/cron.d/reporting_cleanup"/>
<cronjob script="/etc/cron.d/reporting_mails"/>
</cronjobs>
<log-files>
<log title="Postgresql-8.4" no-clear="true">/var/log/postgresql/postgresql-8.4-main.log</log>
<log title="Reporting cleanup">/var/www/innovaphone/apps/innovaphone-reporting/log/reporting_cleanup.log</log>
<log title="innovaphone Reporting">/var/www/innovaphone/apps/innovaphone-reporting/log/innovaphone-reporting.log</log>
<log title="innovaphone Reporting Replication">/var/www/innovaphone/apps/innovaphone-reporting/log/reporting_replication.log</log>
</log-files>
<config-files>
<conf>/etc/postgresql/8.4/main/pg_hba.conf</conf>
<conf>/etc/postgresql/8.4/main/postgresql.conf</conf>
<conf>/home/innovaphone-reporting/reporting.conf</conf>
<conf>/home/root/ssl_cert/server.key</conf>
<conf>/home/root/ssl_cert/server.crt</conf>
<conf>/etc/cron.d/reporting_replication</conf>
<conf>/etc/cron.d/reporting_cleanup</conf>
<conf>/etc/cron.d/reporting_mails</conf>
<conf>/var/www/innovaphone/apps/innovaphone-reporting/report_images</conf>
</config-files>
<backup>
<command title="Save innovaphone Reporting configuration files" cmd="saveinnovaphone-reportingcfgs" script=""/>
<command title="Save innovaphone Reporting database" cmd="saveinnovaphone-reportingdb" script=""/>
<command title="Save innovaphone Reporting log files" cmd="saveinnovaphone-reportinglogs" script=""/>
</backup>
<restore>
<command title="Restore innovaphone Reporting configuration files" cmd="restoreinnovaphone-reportingcfgs" script="">
<action>/etc/init.d/postgresql restart</action>
<action>/etc/init.d/cron restart</action>
</command>
<command title="Restore innovaphone Reporting database" cmd="restoreinnovaphone-reportingdb" script=""/>
</restore>
<uninstall script="/usr/bin/sudo /usr/local/bin/uninstall_script.sh -f 'innovaphone-reporting.xml' -linux_user yes -linux_group yes -database yes -database_user yes -log_script '/var/www/innovaphone/log/appl_uninstall.log'">
<to-delete>
<to-del path="/usr/local/bin/reporting_cleanup.sh"/>
<to-del path="/usr/local/bin/reporting_replication.out"/>
<to-del path="/usr/local/bin/reporting_replication.sh"/>
<to-del path="/home/innovaphone-reporting/tmp"/>
</to-delete>
</uninstall>
<lighttpd-auth>1</lighttpd-auth>
<public-web-paths>
<path>mypbx</path>
<path>user</path>
</public-web-paths>
</code>

===Installed Debian Packages===

The following packages (and their dependencies) are installed with innovaphone Reporting:

* php5-gd
* php5-ldap

===Configuration Files===

pg_hba.conf is the client authentication configuration file and controls which hosts are allowed to connect, how clients
are authenticated, which PostgreSQL user names they can use and which databases they can access.

postgresql.conf is the PostgreSQL configuration file

===Data Files===

If you backup the innovaphone reporting database, you'll get a gz archiv, which contains the whole innovaphone-reporting database.

===Report XML===
The node description also applies for the '''CSV''' columns!

<code type="xml">
<report>
<record>
....
<time time="1301303966" utc="1301303966">2011-03-28 11:19:26</time>
<obj>Saturn</obj>
<id>870998fee909d311b2ec009033105dc9</id>
<call>int</call>
<alert-duration seconds="0">0:00</alert-duration>
<flow>
<ev caller="ep1" ep1_number="101" ep1_name="saturn" ep1_dn="Saturn"
ep2_number="102" ep2_name="uranus" ep2_dn="Uranus" status="co" entry="true"/>
</flow>
<call-duration seconds="2">0:02</call-duration>
<billing-duration seconds="2">0:02</billing-duration>
<conn-duration seconds="2">0:02</conn-duration>
<groups>
<group>test</group>
<group>test2</group>
</groups>
<node>root</node>
<pbx>.</pbx>
<cause></cause>
<dir>o</dir>
<status>co</status>
<type/>
<remote number="102" name="uranus" dn="Uranus"/>
<callback number="456" name="abc" dn="123" time="1301305962">2011-03-28 11:52:42</callback>
</record>
....
</report>
</code>

* time: the node contains a formatted time string of the local time
** attribute '''time''' is a unix timestamp (referring to the local time stamp of the CDR)
** attribute '''utc''' is a unix timestamp (referring to the utc time stamp of the CDR)
* obj: the PBX object name (also called cn)
* id: the conference id of the call
* call: '''int''' (internal) or '''ext''' (external) call
* flow: the call flow
** ev
***ep1 (ep1_number, ep1_name, ep1_dn): the left side of the call
***ep2 (ep2_number, ep2_name, ep2_dn): the right side of the call
***caller: '''ep1''', '''ep2''' or empty, if unknown
***status: '''co''' (connected), '''al''' (alert), '''er''' (error) or '''bu''' (busy) state of the current event
***entry: '''true''' for the entry event of the local object
***type: '''cf''' (call forward), '''ct''' (call transfer)
* groups: the groups of the PBX object
* node: the node of the PBX object
* pbx: the pbx of the PBX object
* cause: the decimal disconnect reason of the call (see [[Reference:ISDN_Cause_Codes]])
* remote: outgoing calls -> dialed endpoint
* remote: incoming calls -> first ep2 above entry event or entry event if this is the first one
* remote: incoming calls with incoming transfer after entry event -> transfer target
* status: outgoing calls -> best found status in call flow
* status: incoming calls -> status of entry event
* type: the type of the entry event or, if not set, the type of the next event, if given
** empty: direct call
** '''ct''': call transfer
** '''cf''': call forward
** '''cct''': call transfer with consultation
** '''pu''': call pickup
* dir: o (outgoing) if the first event is the entry event and the caller is ep1
* dir: i (incoming) if not o
* alert-duration: alert time
* billing-duration: outgoing call -> duration from the first event until the last event in the flow
* billing-duration: incoming call -> duration from the first transfer/forward event until the last event in the flow
* call-duration: duration of the whole call
* conn-duration: duration from the entry event until the event, where the local endpoint isn't connected any more
* callback: '''name''', '''number''', '''dn''' and '''time''' if this call has been callbacked using mypbx (time referrs to the UTC time of the callback)

===Database Structure===

====cdrs====
Each received cdr-xml is formed by a cdr tag and an undefined number of event and group tags.
(Refer to: [[Reference10:Concept_Call_Detail_Record_CDR_PBX|CDR]])

This section is composed by four tables: cdrs, events, groups and cdr_properties.
The first three tables contain the corresponding fields to store the information contained in the cdr, event and group tags. 
Each CDR represents the call in the view of one PBX object. So there might be multiple CDRs for one call if multiple PBX objects are used within the call.

* '''cdr fields:''' id, guid, sys, pbx, node, device, cn, e164, h323, dir, utc, local.
* '''event fields:''' id, msg, type, e164, h323, conf, cause, time, cdr_id, order_index.
* '''group fields:''' id, name, active, type, cdr_id.

'''id''' field is assigned by postgresql for each entry and has nothing to do with the information present in the cdr. It is different for each entry inside the table.

The events table has two additional fields, called cdr_id, to associate these events to the corresponding cdr entry and order_index to keep their position inside the cdr.
Groups table has also the cdr_id field to associate the group entries to the corresponding cdr and events entries.

The '''cdr_properties''' table contains relevant information associated with the call such as call_length, alert_length or call_flow. It also presents a cdr_id field.

====filters====

This section is composed by three tables: filter_columns, filter_conditions and filters.

* '''filter_columns''' is not used for the time being. This is supposed to contain the columns the user wants to see in his report, but right now, just default columns (Time/Object/Duration/Left/Direction/State/Right) are shown.
* '''filter''' contains the filter name and description plus two conditions call_state (No Response, Connected, Busy and No Channel) and direction (Incoming, Outgoing, Transfer and Call Forward).
* '''filter_conditions''' contains the defined conditions for a filter

All three tables are related through an id.

====cdr_users====

This table contains a timestamp '''missed_calls_time''' for the last report access by a user '''cn''' + ('''pbx''' OR '''sys''') with mypbx. It is used to retrieve information about missed calls since the last use of mypbx. 
The timestamp '''clear_report_time''' indicates the last clearance time. 
email, sys (system name) and pbx (PBX name) are also stored for each user.

====replication====

Contains information of the last replication run, which is used to sync master/standby installations.

===Replication===

The replication between the master and standby servers is divided into two steps:

====CDRs====
Both master and standby server keep an information about the last replicated CDR. From this CDR on, they retrieve all CDR guids (32 bytes) from all new CDRs from the other server. If a guid already exists in the local database, the CDR is skipped, otherwise it is replicated. 
So there is a minimal data exchange for already existing CDRs and each new CDR is only processed once.

====Filters/LDAP/Report Mails/Users====
The master server does nothing here, but the '''standby''' deletes all filters, LDAP servers, report mails and users and replicates all from the master. 
So these items from the master server can be used, but not changed, on the standby server.

===Remote Interface===

You can retrieve the PDF/XML/CSV report with a remote interface. 
Make a POST or GET HTTP request to '''http(s)://Linux-IP/apps/innovaphone-reporting/report.php''' with the following parameters:

* remote: mandatory for a remote request!
** '''1'''
* from : the from date/time as UNIX timestamp '''OR''' date/time string as described [ http://www.php.net/manual/de/datetime.formats.php | here ].
* to: the to date/time (format see '''from''')
* [format]: the return format, allowed values:
** '''xml''': default
** '''pdf'''
** '''csv'''
* [sortby] : the report sorting, allowed values:
** '''time''': default
** '''obj''': sort by pbx object name
** '''call-duration'''
** '''alert-duration'''
** '''dir''': sort by call direction
* [sortorder]: the report sort order, allowed values:
** '''ascending''': default
** '''descending'''
* [groupby]: report grouping
** default empty/not set: no grouping
** '''local_stamp''': group by time
** '''cn''': group by pbx object name
* [hidedigits]: hide the last X digits of external numbers
* pbx: search for this PBX (mandatory!)
* pbxobject: search for this PBX object (you can leave this, if you use filterX)
* filterX: use a filter with its name. You can use multiple filters with filter1=test, filter2=test2...
* [filterinfo]: show the filter information in a created report ("true" or "false")
* [lang]: the language, e.g. "en" or "de"
* [displayedduration]:
** '''call_duration''': default Call Duration (Total)
** '''conn_duration''': Call Duration (User)
** '''billing_duration''': Billing Duration
* [anonym]: anonymize internal names/numbers ("true" or "false")
* [bulk]: creates user reports (see [[ #Report_Mails | Report Mails ]])
* [sender]: sender email adress of the report
* [confid]: query calls of a certain conference ID
** you can omit the following fields, if using confid: '''from''', '''to''', '''pbx''', '''pbxobject''', '''filterX'''

Parameters in [] are optional.

'''pbxobject''' supports [[ #PostgreSQL_Patterns | PostgreSQL Patterns ]].

Example:
https://172.16.14.123/apps/innovaphone-reporting/report.php?remote=1&from=2011-03-29&to=2011-03-30&format=xml&pbxobject=Saturn
Gets all records between 2011-03-29 and 2011-03-30 for the pbx object Saturn.

Example:
https://172.16.14.123/apps/innovaphone-reporting/report.php?remote=1&from=2011-03-29&to=2011-03-30&format=xml&filter1=test&filter2=test2
Gets all records between 2011-03-29 and 2011-03-30 for the filters test and test2.

===Tools===

====NetDrive====

[http://www.heise.de/software/download/netdrive/55134 NetDrive] is a usefull webdav client, which can be used to access webdav of the innovaphone application platform.

====PGAdmin====

[http://www.pgadmin.org/ PGAdmin] is an administration tool for PostgreSQL databases.

====Putty====

[http://www.putty.org/ Putty] is SSH client to connect to the linux application platform.

===Call list icons===
The direction of the icon arrow depends on the call flow.

* [[Image:reporting_conn.jpg]]: a connected call
* [[Image:reporting_busy.jpg]]: busy destination
* [[Image:reporting_no_res.jpg]]: no response from destination
* [[Image:reporting_error.jpg]]: an error occurred, like "no channel available" during the call setup
* [[Image:reporting_ct.jpg]]: call transfer
* [[Image:reporting_cct.jpg]]: call transfer with consultation
* [[Image:reporting_cf.jpg]]: call forward
* [[Image:Reporting_pickup.jpg]]: call pickup (or SOAP redirect)
* [[Image:reporting_dir.jpg]]: call direction

A small arrow on a call state icon indicates a callback done with mxPBY, e.g.:
* [[Image:reporting_busy_callback.jpg]]

==Known Problems==
===Replication===
====Callback information====
The callback information get lost in the following scenario:
* The callback CDR is already replicated on both master and standby
* Master or standby is down
* A user calls back the CDR from point 1

====Missed calls====
The information for missed calls is not replicated. So the first time, a standby server is used with mypbx, the missed calls information will be wrong. The second time will be correct again.

===CDRs===
If the innovaphone Reporting is not running, for whatever reaseon, the device, which sends CDRs, currently stores up to 300kB CDRs data. So if one CDR has up to 2kB, 150 CDRs can be stored until the innovaphone Reporting should be up again, to avoid data loss.

===Missing values for PBX drop down box===
If your database currently contains no CDRs of one of your PBX systems, you won't be able to select this system as PBX for report creation or report mail configuration!

===Restoring Database with more than 2GB===

When restoring database using the web browser there is a 2GB upload limit, so if our database have a bigger size the upload will fail.

As alternative solution (if there is enough space):

1. Copy the gz database dump to the webdav folder
2. Uncompress this dump: /bin/gzip -cd /var/www/innovaphone/webdav/dump.gz --uncompress > /tmp/db.dump
3. Start the restore: /usr/local/bin/config.sh postgres db-restore /tmp/pg_schema.dump /tmp/db.dump innovaphone-reporting
4. be patient, this might take a while
5. delete /tmp/db.dump, /var/www/innovaphone/webdav/dump.gz and /tmp/pg_schema.dump (automatically created)

===PDF generation for many CDRs may fail===
You may experience a '''Server error 500''' if you generate PDFs with many CDRs. The PDF library which is used to generate the PDFs fails.
Please generate multiple PDFs with a smaller timespan in such a case.

== Related Articles ==

[[Howto:Integration_reporting_and_voice_recording]]

[[Category:Concept|Reporting]]

Reference10:Concept Reporting

2016-10-17T08:56:55Z

Tru: /* Report Mails */

==Requirements==

It is needed to have the [[Reference10:Concept_Linux_Application_Platform|application platform]] installed and running.

===Calculation of required disk space===

An average CDR requires 2080 bytes of disk space inside the database. 
So '''one GB''' disk space is needed for ~'''516222 CDRs'''. 
One call may have one or multiple CDRs depending on the call flow, the used PBX objects and their configuration.


It is strongly recommended that you try to precalculate your required disk space and configure a suiting value under [[#Configure_scheduled_CDR_cleanup]]. 
Don't forget to configure the alarm server under [[Reference10:Concept_Linux_Application_Platform#Alarm_Server]] to receive an alarm if the disk is nearly full (10% disk space remaining).


==Installation==

Download the latest version of innovaphone reporting.

Log into the application platform, go to the Applications tag, click on [[ Reference10:Concept_Linux_Application_Platform#Upload.2FUpdate|Upload/Update]] and upload the downloaded file.
The installation will start automatically and the page will refresh every two seconds showing the installation process.
If there is no error during the installation you will see at the end "Installation was succesfull". Otherwise,
you will get "installation failed" and the reason why it went wrong.

===Hotfix===
If you have already installed the latest version of Reporting, simply download the Reporting...HotfixIncremental for your platform (VM or IPxx10) or if you have missed some hotfixes, download the Reporting...HotfixCumulative archive, which contains all hotfixes since hotfix1.
 
 
Upload this hotfix archive [[Reference10:Concept_Linux_Application_Platform#Upload.2FUpdate|here]].

==Configuration==
===Device===

====License====
It is required to have a Reporting license installed on your device. Check under [[ Reference10:General/License ]] if you already have one.

Set the Reporting flag for each PBX object, which should be reported on the objects properties page.

====CDR Gateway====
Any innovaphone device which sends [[Reference10:Concept_Call_Detail_Record_CDR_PBX|CDRs]] to the reporting application must have at least one CDR interface configured under [[ Reference10:Gateway/CDR ]]:

* Type: LOCAL-AP or REMOTE-AP/REMOTE-AP-S

If HTTP/HTTPS is selected then some other parameters must be set:

* Address: ip address of the application platform
* Port: 80 for REMOTE-AP
* Port: 443 for REMOTE-AP-S
* Method: POST/GET
* Path: ap/cdr.fcgi

The application platform is by default password protected, so you'll have to perform one of these steps: 

* configure an authenticated URL for '''ap/cdr.fcgi''' under [[ Reference10:Services/HTTP/Client ]] (recommended)
** If you configure an authenticated URL (with the linux webserver credentials), don't forget to configure port 80 or port 443 for secure transport (Remote-AP-S) like https://111.111.111.111:443/ap or http://111.111.111.111:80/ap
* configure '''ap/cdr.fcgi''' as public web path on the innovaphone application platform [[ Reference10:Concept_Linux_Application_Platform#Change_web_server_properties_and_public_access_to_the_web.2Fwebdav|Public Web Paths ]]

Configure a second CDR interface, if you use [[#Replication|Replication]].

====Enable PBX CDRs====
Enable the "Generate CDRs" flag under [[ Reference10:PBX/Config/General ]].

===innovaphone Application Platform===

If the reporting URL/user/password is not configured in your device as authenticated URL, configure '''ap/cdr.fcgi''' as public web path on the innovaphone application platform [[ Reference10:Concept_Linux_Application_Platform#Change_web_server_properties_and_public_access_to_the_web.2Fwebdav|Public Web Paths ]].

===Database===

Reporting creates the innovaphone-reporting database to store CDRs sent from any innovaphone devices (appendix 7.6 explains the database structure).
PostgreSQL is also available for other applications and any of them could create its own database.

====Password====

Reporting creates the database user '''innovaphone-reporting''' with default password '''reporting'''.
This password may be changed at the innovaphone Reporting page under Config/Database.

====Remote Access====

There are tools (PgAdmin III) that allow to connect to application databases remotely.
It is first needed to configure the IP you are connecting from under Config/Database at the innovaphone reporting page.

For the PgAdmin III it is imporant to use innovaphone-reporting as Service-DB (Wartungs-DB). Default login credentials - User: innovaphone-reporting - Password: reporting

====Delete CDRs====

You can delete CDRs for certain/all users in a certain timespan. If you enter '''%''' as object, all users are selected.

Note that PostgreSQL doesn't free the space on the disk! If you need free disk space, issue this command on the shell:
''sudo -u postgres vacuumdb -f innovaphone-reporting''
This may take some time and CDRs won't be received during this time.

====Configure scheduled CDR cleanup====

If you activate scheduled cleanup, CDRs older than the configured amount of months will be automatically deleted. 
The scheduled task is started once a day at 2 AM.

===PBX===

If you use multiple PBX devices which are not Master/Slave, you have to select, which identifier is unique for a user under Config/PBX:
* System Name (default)
* PBX Name

The selected value determines, which values are shown in the PBX dropdown box for report creation or report mail configuration.

===Replication===

You can configure a second innovaphone application platform with an installed innovaphone Reporting for replication purposes. 

* Mode:
** '''Off''': no replication
** '''Master''': the local server is the master server
** '''Standby''': the local server is the standby server, filters will be replicated from the master and can't be changed here
* Master/Standby Server: the IP address of the master or standby server
* Database password: the PostgreSQL database password of the other server (default is '''reporting''').
* Synchronisation interval: the interval in minutes (range 1-60) in which a sync is done

Now configure a second [[#CDR_Gateway|CDR Gateway]] for the standby server.

The current status can be seen here too. If the status is '''Failed''' take a look at the log file '''innovaphone Reporting Replication''' under [[ Reference10:Concept_Linux_Application_Platform#Logs|Diagnostics/Logs]] or look at the last trace output at the bottom of the page.
 
 
How replication works is described [[#Replication_2|here]].

===LDAP===

Several LDAP servers and dialing locations can be configured here. 

PBX field must correspond to a name of a PBX since PBX's names are available in CDRs. The received CDR is parsed to get the PBX name and this name will be used to find the corresponding LDAP server and dialing location needed to resolve names.

Each configured LDAP server and dialing location can be activated/deactivated with the '''active''' flag.

[[Image:ldap_update.png]]

If the country where you configure LDAP does not have Trunk/National prefix you should leave "National Prefix" and "Area Code" empty.

In the number Attributes field please do '''not''' add any additional characters to the attributes like ":P", ":D" or "@", for instance "homePhone:P, mobile:M, telephoneNumber:D". This does not work. That would be correct: "homePhone, mobile, telephoneNumber"

LDAP Internal Search flag allows reporting to perform name resolution also for internal numbers.

===Report Mails===

Automatic report generation can be configured here:

* '''time''': daytime at which the report is sent
* '''user reports''':
** Creates for each matching user a separate report
** Users are matched by '''Object (Long Name)'''
** A user report only contains calls for this user
** The email address of the user is built by its '''H323 name''' and the '''System Name''' of its PBX (h323@systemname) or determined by the E-Mail field of the user
* '''interval''':
** daily: Mail will be send daily with the automatic period "last day"
** weekly: Mail will be send weekly with the automatic period "last week"
** monthly: Mail will be send daily with the automatic period "last month"
* '''day''': the day, at which the report is sent
* '''mail adresses''': recipients of the report (comma separated)
* '''Sender E-Mail address''': sender email address, which may be present as [[ Reference10:Concept_Linux_Application_Platform#Relay_Hosts | relay host ]]
* '''compress''': compress the attachment or not
* '''sort by'''
* '''sort order'''
* '''language'''
* '''send time''': the time of a day, when the report is sent

The explanation for the other settings can be found [[ #Report_Creation | here. ]] 

[[Image:mails.png]]

===Users===

You can configure multiple users, who shall have access to reports without having access to the whole reporting configuration. 
The user can login with his user name and password on: 

http(s)://Linux-IP/apps/innovaphone-reporting/user/login.php

The admin can assign one or more base filters to the user. A base filter is explained [[ #Base_filter | here]]. 
If the user creates new reports, new own filters or report mails, he '''has''' to use one of his assigned base filters.

If you are using multiple PBX systems, the user has only access to these systems, which are configured in the base filters of the user.
If the user has no base filter with a limitation to a certain "System Name"/"PBX Name" (depends on your [[ #PBX | PBX configuration ]]),
he will have access to all systems!

[[Image:users.jpg]]

====User Login====

A logged in user can create reports, own filters and report mails based on his assigned base filters.

[[Image:Userlogin.jpg]]

===Images===

You may upload images to be used as logo or footer in pdf reports. 

Logos must be 32x32 and footer can have a maximum width of 450 pixels and a maximum height of 50 pixels. 

These images can have jpeg or png format. 

===Relay CDRs===

Relay CDRs can be stored in log files by the Reporting application. Configure a CDR gateway as already described and relay CDRs will be written to the webdav file '''/cdr/cdr.txt'''.
The file is rotated on 1 MB size. The first rotated file is uncompressed, further files will be gz compressed. Max ten files are kept. Older files will be deleted: 
* cdr.txt
* cdr.txt.1
* cdr.txt.2.gz
* cdr.txt.3.gz
* cdr.txt.4.gz
* cdr.txt.5.gz
* cdr.txt.6.gz
* cdr.txt.7.gz
* cdr.txt.8.gz
* cdr.txt.9.gz

===innovaphone-reporting web access===

You can configure a separate authentication for the innovaphone-reporting web site [[Reference10:Concept_Linux_Application_Platform#Change_application_access_credentials|here]]. 
One can just login on the reporting site with this access.

===Integration Voice recorder===

The innovaphone voice recording can be integrated and a remote control of the player is possible, see relative article.

==Filters==
===General===

Filters are set up to create reports based on certain conditions. A filter can have multiple conditions and multiple filters can be combined on report creation (combine is performed with an '''OR'''). 
A filter has a unique '''name''' with an optional '''description'''.

===Conditions===

[[Image:filter.png]]

There are five or seven condition sections depending on what is selected under '''States'''. Conditions inside same section are '''OR''' associated while different sections are '''AND''' associated.
 

(Object == Terra '''OR''' Object == Uranus) '''AND''' (PBX == sifi) '''AND''' (Number == 0049%)

====Base filter====

If you select another filter as base filter, the conditions of the base filter are implicitly '''AND''' conjuncted, when the current filter is used. 
So if the base filter defines two PBX values, e.g. "Berlin" and "Hamburg" and the current filter defines one PBX value, e.g. "Berlin", only objects of the PBX "Berlin" will be filtered: 

(pbx="Berlin") AND (pbx="Berlin" OR pbx="Hamburg")

If a user defines an own filter for his reports, he has to use a base filter, which he is allowed to use. So each filter, which he uses, will have at least one base filter condition, which the admin has defined.

You have to take care with the conditions of the current filter and the base filter,
as it is now easy to create a filter with mutually exclusive conditions, e.g. if
the filter has pbx="Berlin" and the base filter pbx="Hamburg" => no matching records.

====Anonym====

If you check this flag, a report created with this filter or with a filter, where this filter is a basefilter, will by anonymized.

====Local====

Define one ore more conditions for the local party, defined by:

* Object: the cn/PBX object name
* Number: the number
* Groups: a group of the PBX object

====Remote====

Define one or more conditions for the remote party, defined by:

* Number: the number
* Remote display name: the display name

====PBX====

Define one ore more conditions for the PBX, defined by:

* PBX: the PBX name
* Node: the node name

====States====

* No Response
* Connected
* Busy
* No Channel

====Directions====

* Incoming
* Outgoing
* Transfer: calls, which have been transferred to the current local party
* Call Forward: calls, which have been forwarded to the current local party

====Call Duration====

Time the call was connected.

This condition will be '''AND''' with the others if all '''States''' are selected. 
If Busy, No Channel or No Response is unselected, then the filter will search for Connected calls with connected time greater or smaller than '''Call Duration'''.

====Alert Duration====

Time the call was ringing independent of the status of the call afterwards.

This condition will be '''AND''' with the others if all '''States''' are selected. 
If Busy, No Channel or Connected is unselected, then the filter will search only for Not Connected Calls that were ringing more or less time than '''Alert Duration'''.

====Report times====

Define the time where calls should be counted. 
You can optionally define the weekday(s) of calls.

====Images====

* Logo: This must be 32x32 pixel image in jpeg or png format. 
* Footer: Maximum width of 450 pels and maximum height of 50 pels. Also jpeg or png format. 

====Using Patterns====

You can use these [[ #PostgreSQL_Patterns | PostgreSQL Patterns ]] for every condition.

==Report Creation==
===General===

It is possible to generate call lists for single users or more complex reports by means of filters.

===Web Interface===

Reporting application provides a web interface to generate reports.

[[Image:Report_hide.png]]

* '''PBX''': select the PBX for the report. The values of the drop down box depend on your [[#PBX | PBX configuration]]
* '''Object (Long Name)''': corresponds to the PBX Long Name assigned to a specific user (% is a special postgresql character, which matches any string)
* '''Filter''': one or multiple filters can be defined ('''OR''' joined)
* '''Group by''': the result can be grouped by Date or Object
* '''Hide last X digits''': you may replace the last digits of an external number with a '*'.
** LDAP must be configured in order to use this capability but if you want no LDAP funtionality, just unset the Active Box in LDAP.
** Actually, the pbx/phys value of a call is matched against the LDAP pbx value and if the number starts with the external line prefix.
* '''Anonym''': do not show internal names/numbers
** If anonym is set, hide last digits is set to 3, if not set
* '''Filter Info''': the report will contain information about the configured settings and filter information
* '''Displayed Duration''':
** Call Duration (Total): the total call duration, e.g. with the duration of a subsequent transfer
** Call Duration (User): just the time, the user was connected
** Billing Duration: the duration, a user must be billed for
** None of these durations contain the alert duration, which is separatly listed

[[Image:reporting_report.png | A normal report. The summary shows incoming / outgoing summaries]]

[[Image:grouped_report.png | A grouped report. Each group has an own summary]]

====Print====

Click the print icon to open a printable version of the report.

====Save====
You can save the report as '''pdf''' or as '''xml''' by using the corresponding icon. 
You can also download a report in '''csv''' format without call history. The report uses '''comma''' as delimeter character, '''"''' as text qualifier and '''PBX Object/Remote Party''' columns should be defined as Text (avoid telephone numbers to be considered as numbers by Excel). '''UTF-8''' must be used as character set. 

====Sorting====

Each sortable column has a clickable column head. This sorting will be also used when opening the printable version or saving the report as PDF.

====Icons====
The icons are explained in the [[#Call list icons|appendix]].

===Remote Interface===

See [[#Remote_Interface_2|Remote Interface Appendix]]

==Backup and Restore==

You can both manually and automatically backup the database and configuration files for Reporting under [[Reference10:Concept_Linux_Application_Platform#Backup|Administration/Backup]] in the application platform.

Configuration details for the update server can be found [[Reference10:Concept_Linux_Application_Platform#Backup|here]].

===Configuration Files===

'''saveinnovaphone-reportingcfgs''' is the command used to automatically save configuration files with the [[Reference10:Concept_Linux_Application_Platform#Command_File|Command File]].

===Data===

'''saveinnovaphone-reportingdb''' is the command to automatically backup the whole innovaphone Reporting database with the [[Reference10:Concept_Linux_Application_Platform#Command_File|Command File]].

If you restore the reporting database, you should keep in mind, that this might take several hours for a system
on a CF card, depending on the size of the restored database. The backup process itself is quite fast with a few minutes.

===Logs===

'''saveinnovaphone-reportinglogs''' to save log files with the [[Reference10:Concept_Linux_Application_Platform#Command_File|Command File]].

==Appendix==
===PostgreSQL Patterns===
For filter conditions or for the pbx object value you can use the following patterns inside a string:

* '''%''': matches any string of zero or more characters
* '''_''': matches any single character

Example:
'''Sat%''' will match all pbx objects, which start with the string '''Sat'''.

We do always perform case insensitiv searches!

===innovaphone Reporting XML===
<code type="xml">
<?xml version="1.0" encoding="utf-8"?>
<application>
<name>innovaphone Reporting</name>
<desc>Reporting software</desc>
<directory>innovaphone-reporting</directory>
<href>report.php</href>
<linux-username>innovaphone-reporting</linux-username>
<packages>
<package>php5-gd</package>
<package>php5-ldap</package>
</packages>
<database name="innovaphone-reporting" username="innovaphone-reporting"/>
<cronjobs>
<cronjob script="/etc/cron.d/reporting_replication"/>
<cronjob script="/etc/cron.d/reporting_cleanup"/>
<cronjob script="/etc/cron.d/reporting_mails"/>
</cronjobs>
<log-files>
<log title="Postgresql-8.4" no-clear="true">/var/log/postgresql/postgresql-8.4-main.log</log>
<log title="Reporting cleanup">/var/www/innovaphone/apps/innovaphone-reporting/log/reporting_cleanup.log</log>
<log title="innovaphone Reporting">/var/www/innovaphone/apps/innovaphone-reporting/log/innovaphone-reporting.log</log>
<log title="innovaphone Reporting Replication">/var/www/innovaphone/apps/innovaphone-reporting/log/reporting_replication.log</log>
</log-files>
<config-files>
<conf>/etc/postgresql/8.4/main/pg_hba.conf</conf>
<conf>/etc/postgresql/8.4/main/postgresql.conf</conf>
<conf>/home/innovaphone-reporting/reporting.conf</conf>
<conf>/home/root/ssl_cert/server.key</conf>
<conf>/home/root/ssl_cert/server.crt</conf>
<conf>/etc/cron.d/reporting_replication</conf>
<conf>/etc/cron.d/reporting_cleanup</conf>
<conf>/etc/cron.d/reporting_mails</conf>
<conf>/var/www/innovaphone/apps/innovaphone-reporting/report_images</conf>
</config-files>
<backup>
<command title="Save innovaphone Reporting configuration files" cmd="saveinnovaphone-reportingcfgs" script=""/>
<command title="Save innovaphone Reporting database" cmd="saveinnovaphone-reportingdb" script=""/>
<command title="Save innovaphone Reporting log files" cmd="saveinnovaphone-reportinglogs" script=""/>
</backup>
<restore>
<command title="Restore innovaphone Reporting configuration files" cmd="restoreinnovaphone-reportingcfgs" script="">
<action>/etc/init.d/postgresql restart</action>
<action>/etc/init.d/cron restart</action>
</command>
<command title="Restore innovaphone Reporting database" cmd="restoreinnovaphone-reportingdb" script=""/>
</restore>
<uninstall script="/usr/bin/sudo /usr/local/bin/uninstall_script.sh -f 'innovaphone-reporting.xml' -linux_user yes -linux_group yes -database yes -database_user yes -log_script '/var/www/innovaphone/log/appl_uninstall.log'">
<to-delete>
<to-del path="/usr/local/bin/reporting_cleanup.sh"/>
<to-del path="/usr/local/bin/reporting_replication.out"/>
<to-del path="/usr/local/bin/reporting_replication.sh"/>
<to-del path="/home/innovaphone-reporting/tmp"/>
</to-delete>
</uninstall>
<lighttpd-auth>1</lighttpd-auth>
<public-web-paths>
<path>mypbx</path>
<path>user</path>
</public-web-paths>
</code>

===Installed Debian Packages===

The following packages (and their dependencies) are installed with innovaphone Reporting:

* php5-gd
* php5-ldap

===Configuration Files===

pg_hba.conf is the client authentication configuration file and controls which hosts are allowed to connect, how clients
are authenticated, which PostgreSQL user names they can use and which databases they can access.

postgresql.conf is the PostgreSQL configuration file

===Data Files===

If you backup the innovaphone reporting database, you'll get a gz archiv, which contains the whole innovaphone-reporting database.

===Report XML===
The node description also applies for the '''CSV''' columns!

<code type="xml">
<report>
<record>
....
<time time="1301303966" utc="1301303966">2011-03-28 11:19:26</time>
<obj>Saturn</obj>
<id>870998fee909d311b2ec009033105dc9</id>
<call>int</call>
<alert-duration seconds="0">0:00</alert-duration>
<flow>
<ev caller="ep1" ep1_number="101" ep1_name="saturn" ep1_dn="Saturn"
ep2_number="102" ep2_name="uranus" ep2_dn="Uranus" status="co" entry="true"/>
</flow>
<call-duration seconds="2">0:02</call-duration>
<billing-duration seconds="2">0:02</billing-duration>
<conn-duration seconds="2">0:02</conn-duration>
<groups>
<group>test</group>
<group>test2</group>
</groups>
<node>root</node>
<pbx>.</pbx>
<cause></cause>
<dir>o</dir>
<status>co</status>
<type/>
<remote number="102" name="uranus" dn="Uranus"/>
<callback number="456" name="abc" dn="123" time="1301305962">2011-03-28 11:52:42</callback>
</record>
....
</report>
</code>

* time: the node contains a formatted time string of the local time
** attribute '''time''' is a unix timestamp (referring to the local time stamp of the CDR)
** attribute '''utc''' is a unix timestamp (referring to the utc time stamp of the CDR)
* obj: the PBX object name (also called cn)
* id: the conference id of the call
* call: '''int''' (internal) or '''ext''' (external) call
* flow: the call flow
** ev
***ep1 (ep1_number, ep1_name, ep1_dn): the left side of the call
***ep2 (ep2_number, ep2_name, ep2_dn): the right side of the call
***caller: '''ep1''', '''ep2''' or empty, if unknown
***status: '''co''' (connected), '''al''' (alert), '''er''' (error) or '''bu''' (busy) state of the current event
***entry: '''true''' for the entry event of the local object
***type: '''cf''' (call forward), '''ct''' (call transfer)
* groups: the groups of the PBX object
* node: the node of the PBX object
* pbx: the pbx of the PBX object
* cause: the decimal disconnect reason of the call (see [[Reference:ISDN_Cause_Codes]])
* remote: outgoing calls -> dialed endpoint
* remote: incoming calls -> first ep2 above entry event or entry event if this is the first one
* remote: incoming calls with incoming transfer after entry event -> transfer target
* status: outgoing calls -> best found status in call flow
* status: incoming calls -> status of entry event
* type: the type of the entry event or, if not set, the type of the next event, if given
** empty: direct call
** '''ct''': call transfer
** '''cf''': call forward
** '''cct''': call transfer with consultation
** '''pu''': call pickup
* dir: o (outgoing) if the first event is the entry event and the caller is ep1
* dir: i (incoming) if not o
* alert-duration: alert time
* billing-duration: outgoing call -> duration from the first event until the last event in the flow
* billing-duration: incoming call -> duration from the first transfer/forward event until the last event in the flow
* call-duration: duration of the whole call
* conn-duration: duration from the entry event until the event, where the local endpoint isn't connected any more
* callback: '''name''', '''number''', '''dn''' and '''time''' if this call has been callbacked using mypbx (time referrs to the UTC time of the callback)

===Database Structure===

====cdrs====
Each received cdr-xml is formed by a cdr tag and an undefined number of event and group tags.
(Refer to: [[Reference10:Concept_Call_Detail_Record_CDR_PBX|CDR]])

This section is composed by four tables: cdrs, events, groups and cdr_properties.
The first three tables contain the corresponding fields to store the information contained in the cdr, event and group tags. 
Each CDR represents the call in the view of one PBX object. So there might be multiple CDRs for one call if multiple PBX objects are used within the call.

* '''cdr fields:''' id, guid, sys, pbx, node, device, cn, e164, h323, dir, utc, local.
* '''event fields:''' id, msg, type, e164, h323, conf, cause, time, cdr_id, order_index.
* '''group fields:''' id, name, active, type, cdr_id.

'''id''' field is assigned by postgresql for each entry and has nothing to do with the information present in the cdr. It is different for each entry inside the table.

The events table has two additional fields, called cdr_id, to associate these events to the corresponding cdr entry and order_index to keep their position inside the cdr.
Groups table has also the cdr_id field to associate the group entries to the corresponding cdr and events entries.

The '''cdr_properties''' table contains relevant information associated with the call such as call_length, alert_length or call_flow. It also presents a cdr_id field.

====filters====

This section is composed by three tables: filter_columns, filter_conditions and filters.

* '''filter_columns''' is not used for the time being. This is supposed to contain the columns the user wants to see in his report, but right now, just default columns (Time/Object/Duration/Left/Direction/State/Right) are shown.
* '''filter''' contains the filter name and description plus two conditions call_state (No Response, Connected, Busy and No Channel) and direction (Incoming, Outgoing, Transfer and Call Forward).
* '''filter_conditions''' contains the defined conditions for a filter

All three tables are related through an id.

====cdr_users====

This table contains a timestamp '''missed_calls_time''' for the last report access by a user '''cn''' + ('''pbx''' OR '''sys''') with mypbx. It is used to retrieve information about missed calls since the last use of mypbx. 
The timestamp '''clear_report_time''' indicates the last clearance time. 
email, sys (system name) and pbx (PBX name) are also stored for each user.

====replication====

Contains information of the last replication run, which is used to sync master/standby installations.

===Replication===

The replication between the master and standby servers is divided into two steps:

====CDRs====
Both master and standby server keep an information about the last replicated CDR. From this CDR on, they retrieve all CDR guids (32 bytes) from all new CDRs from the other server. If a guid already exists in the local database, the CDR is skipped, otherwise it is replicated. 
So there is a minimal data exchange for already existing CDRs and each new CDR is only processed once.

====Filters/LDAP/Report Mails/Users====
The master server does nothing here, but the '''standby''' deletes all filters, LDAP servers, report mails and users and replicates all from the master. 
So these items from the master server can be used, but not changed, on the standby server.

===Remote Interface===

You can retrieve the report xml/pdf with a remote interface. 
Make a POST or GET HTTP request to '''http(s)://Linux-IP/apps/innovaphone-reporting/report.php''' with the following parameters:

* remote: mandatory for a remote request!
** '''1'''
* from : the from date/time as UNIX timestamp '''OR''' date/time string as described [ http://www.php.net/manual/de/datetime.formats.php | here ].
* to: the to date/time (format see '''from''')
* [format]: the return format, allowed values:
** '''xml''': default
** '''pdf'''
** '''csv'''
* [sortby] : the report sorting, allowed values:
** '''time''': default
** '''obj''': sort by pbx object name
** '''call-duration'''
** '''alert-duration'''
** '''dir''': sort by call direction
* [sortorder]: the report sort order, allowed values:
** '''ascending''': default
** '''descending'''
* [groupby]: report grouping
** default empty/not set: no grouping
** '''local_stamp''': group by time
** '''cn''': group by pbx object name
* [hidedigits]: hide the last X digits of external numbers
* pbx: search for this PBX (mandatory!)
* pbxobject: search for this PBX object (you can leave this, if you use filterX)
* filterX: use a filter with its name. You can use multiple filters with filter1=test, filter2=test2...
* [filterinfo]: show the filter information in a created report ("true" or "false")
* [lang]: the language, e.g. "en" or "de"
* [displayedduration]:
** '''call_duration''': default Call Duration (Total)
** '''conn_duration''': Call Duration (User)
** '''billing_duration''': Billing Duration
* [anonym]: anonymize internal names/numbers ("true" or "false")
* [bulk]: creates user reports (see [[ #Report_Mails | Report Mails ]])
* [sender]: sender email adress of the report
* [confid]: query calls of a certain conference ID
** you can omit the following fields, if using confid: '''from''', '''to''', '''pbx''', '''pbxobject''', '''filterX'''

Parameters in [] are optional.

'''pbxobject''' supports [[ #PostgreSQL_Patterns | PostgreSQL Patterns ]].

Example:
https://172.16.14.123/apps/innovaphone-reporting/report.php?remote=1&from=2011-03-29&to=2011-03-30&format=xml&pbxobject=Saturn
Gets all records between 2011-03-29 and 2011-03-30 for the pbx object Saturn.

Example:
https://172.16.14.123/apps/innovaphone-reporting/report.php?remote=1&from=2011-03-29&to=2011-03-30&format=xml&filter1=test&filter2=test2
Gets all records between 2011-03-29 and 2011-03-30 for the filters test and test2.

===Tools===

====NetDrive====

[http://www.heise.de/software/download/netdrive/55134 NetDrive] is a usefull webdav client, which can be used to access webdav of the innovaphone application platform.

====PGAdmin====

[http://www.pgadmin.org/ PGAdmin] is an administration tool for PostgreSQL databases.

====Putty====

[http://www.putty.org/ Putty] is SSH client to connect to the linux application platform.

===Call list icons===
The direction of the icon arrow depends on the call flow.

* [[Image:reporting_conn.jpg]]: a connected call
* [[Image:reporting_busy.jpg]]: busy destination
* [[Image:reporting_no_res.jpg]]: no response from destination
* [[Image:reporting_error.jpg]]: an error occurred, like "no channel available" during the call setup
* [[Image:reporting_ct.jpg]]: call transfer
* [[Image:reporting_cct.jpg]]: call transfer with consultation
* [[Image:reporting_cf.jpg]]: call forward
* [[Image:Reporting_pickup.jpg]]: call pickup (or SOAP redirect)
* [[Image:reporting_dir.jpg]]: call direction

A small arrow on a call state icon indicates a callback done with mxPBY, e.g.:
* [[Image:reporting_busy_callback.jpg]]

==Known Problems==
===Replication===
====Callback information====
The callback information get lost in the following scenario:
* The callback CDR is already replicated on both master and standby
* Master or standby is down
* A user calls back the CDR from point 1

====Missed calls====
The information for missed calls is not replicated. So the first time, a standby server is used with mypbx, the missed calls information will be wrong. The second time will be correct again.

===CDRs===
If the innovaphone Reporting is not running, for whatever reaseon, the device, which sends CDRs, currently stores up to 300kB CDRs data. So if one CDR has up to 2kB, 150 CDRs can be stored until the innovaphone Reporting should be up again, to avoid data loss.

===Missing values for PBX drop down box===
If your database currently contains no CDRs of one of your PBX systems, you won't be able to select this system as PBX for report creation or report mail configuration!

===Restoring Database with more than 2GB===

When restoring database using the web browser there is a 2GB upload limit, so if our database have a bigger size the upload will fail.

As alternative solution (if there is enough space):

1. Copy the gz database dump to the webdav folder
2. Uncompress this dump: /bin/gzip -cd /var/www/innovaphone/webdav/dump.gz --uncompress > /tmp/db.dump
3. Start the restore: /usr/local/bin/config.sh postgres db-restore /tmp/pg_schema.dump /tmp/db.dump innovaphone-reporting
4. be patient, this might take a while
5. delete /tmp/db.dump, /var/www/innovaphone/webdav/dump.gz and /tmp/pg_schema.dump (automatically created)

===PDF generation for many CDRs may fail===
You may experience a '''Server error 500''' if you generate PDFs with many CDRs. The PDF library which is used to generate the PDFs fails.
Please generate multiple PDFs with a smaller timespan in such a case.

== Related Articles ==

[[Howto:Integration_reporting_and_voice_recording]]

[[Category:Concept|Reporting]]

Howto:Softwarephone recommended settings

2016-09-15T16:29:28Z

Tru: /* Problem Details */

File:Policy-basedQoS.jpg

2016-09-15T16:28:47Z

Tru:

Howto:Softwarephone recommended settings

2016-09-15T16:28:12Z

Tru:

Howto:SBC scaling for large number of channels

2016-09-05T14:56:56Z

Tru:

==Applies To==
This information applies to:

* SBC functionality on Gateways or IPVA with v12r1 or later



==More Information==

===Preamble===
With the innovaphone SBC, we provide approximately 100 - 200 concurrent Channels per Gateway or IPVA. In bigger Scenarios where a few hundred (or more) Channels are required, several Gateways can be joined to a "Load Balancing Scenario" to provide a large number of Channels.

Because a lot of SIP Provider does not support multiple registrations from many different Gateways and cannot guarantee an evenly Call distribution (Load Balancing), a dedicated SBC as SIP-Gateway for registrations is needed.

'''Please ask your SIP Provider if he provides Multiple Registrations and Load Balancing before you start with the planning of the scenario.'''

This document describes the principles how to configure a "Load Balancing Scenario" with the reference to an example.

'''Be aware that this is just an example to explain how it works; maybe it’s a little bit different in your scenario - depending on the SIP Provider! '''

===Function Principle===

The Limitation of the concurrent Channels per Gateway is based on the Media Relay Feature. If this Feature is enabled (and it’s mandatory for the SBC), the Channels are limited.

To bypass this limit, the idea is:
* to have a dedicated Gateway without Media-Relay. This acts only as Registration Gateway to the SIP Provider. Without Media Relay this Gateway can handle a very large number of calls. We call it '''"Register-GW"''' in this document.
* to use as many Gateways as needed for Media Relay. All calls should be evenly distributed on this Gateway to have a "Load Balance Scenario". We call them '''"Relay-GWs"''' in this document.

'''''Register-GW'''''

* On the "Register-GW" we need a PBX because only with the PBX we have an evenly distribution to several Gateways. Therefore the PBX must be enabled (Master) on this Gateway, but we need only two Gateway Objects in it. The first is for the registration from the Provider- SIP-Interface (on the same GW) and the second is for all registrations from the "Relay-GWs". No other object is needed.
* The SIP-Interface to the Provider is similar to the SBC of the "Common Scenario". It has two registrations, one to the SIP Provider and another to the internal PBX. Only Media relay is disabled.
* The default Routes between SIP Provider and PBX must be adapted.

'''''Relay-GWs'''''

The "Relay-GWs" are serving the Media Relay Part in this scenario. On each "Relay-GW" there are two registrations and simple routes between it.
* One registration to the "Register-GW"- PBX with Media Relay and the same Media Properties like the SIP Interface to the Provider at the "Register-GW".
* One registration to the real PBX w/o Media Relay with default settings.

[[Image:SBC_scenarios.jpg]]

==Configuration Example==
'''The following example shows how a configuration can be done, maybe it’s a little bit different in your scenario. Depending on the SIP Provider and the needed Number Mappings or Routes, there can be a lot of alternative Configurations'''

===Overview===

{| border="0"
|----
|'''1)''' On the "Register-GW " the PBX must be enabled and

two Gateway Objects with a Number must be created. In

this example we have chosen the '''Prefix "1" for calls to'''

'''the SIP Provider''' and the '''Prefix "2" for calls to the'''

'''internal PBX'''.

'''2)''' The SIP Interface must be configured without Media

Relay. The SIP Registration goes to the Provider; the

internal Registration goes to the local PBX.

'''3)''' In the Routes '''TO the "PBX of the Register-GW"''', a

leading '''"2" must be added''' to reach the opposite

GW-Object in the "PBX of the Register-GW".

In the Routes '''FROM the "PBX of the Register-GW"''', the

leading '''"1" must be cut''' because it's not needed anymore.

'''4a)''' On the "Relay Gateway" one Interface must be

configured for the registration to the '''"PBX of the'''

'''Register-GW" with Media Relay'''

'''4b)''' On the "Relay Gateway" one Interface must be

configured for the registration to the '''Regular '''

''' PBX without Media Relay'''

'''5)''' In the Routes '''FROM the Regular PBX''', the

'''Tone Interface and a leading "1" must be added''' to reach

the opposite GW-Object in the "PBX of the Register-GW".

In the Routes '''TO the Regular PBX''', the '''leading "2"'''

'''must be cut''' because it's not needed anymore.
| .
|[[Image:ConfigurationOverview.jpg]]
|----
|}

----
===Configuring the Customers regular PBX===

'''1. Create a Trunk Object in the regular PBX'''

Of Course, in the regular PBX (where usually the Users are registered), a Trunk Object must be existing for external calls.

[[Image: RealPBX_1TrunkObject.jpg]]

===Configuring the Registration Gateway===

'''2. Enable the PBX on the Register-GW'''

On the same GW where the SBC (SIP Interface to Provider) is configured, a PBX must be created. Any System or PBX Name can be chosen because it’s normally an isolated PBX. But two Port Licenses are needed for the two Gateway registrations.

[[Image: RegisterGW_1MasterPBX.jpg]]

'''3. Create two Gateway Objects'''

Two Gateway Objects must be created on this PBX. Defaults settings can be used, but each Gateway Object must have a Number.
In this example we have chosen the '''Prefix "1" for calls to the SIP Provider''' and the '''Prefix "2" for calls to the internal PBX'''.

[[Image: RegisterGW_2PBX-GatewayObjects.jpg]]

'''4. Configure SIP Interface'''

At the SIP Interface to the Provider, nothing special must be configured, please use the Provider specific settings from the Profiles or from the Provider Documentation.
Only Media Relay must be set to "off" and the internal registration goes to the PBX on its own Gateway.

[[Image: RegisterGW_3SIP-Interface.jpg]]

'''4. Modification of the Routes'''

Following modification must be done in the Routes:
* The '''"2"''' (Prefix of the second Gateway Object in the PBX) '''must be added''' to Numbers that goes to the PBX.
* If there is a default Tone Mapping, it can be disabled or deleted.
* The leading '''"1"''' (Prefix of the first GW Object in the PBX) '''must be cut''' from each Number that comes from the PBX.

[[Image: RegisterGW_4Routing.jpg]]

=== Configuring the SBC Relay Gateways===
The following configurations are absolute identical on each Relay Gateway.

'''5. Creation of GW Interfaces'''

Two GW Interfaces must be created.
The first one is to register with the Second Gateway Object on the PBX of the "Register-GW". Here, the Media Relay must be enabled.
The second one is to register with the Trunk Object on the regular PBX. Here, the Media Relay must be disabled. All other settings (like Codecs, T.38, etc.) are depending on your requirements.

[[Image: RelayGW_1GW-Interfaces.jpg]]

'''6. Creation of the Routes'''

Routes must be created between these Gateway Interfaces:
* The leading '''"2"''' (Prefix of the second Gateway Object in the Register GW PBX) '''must be cut''' from each Number that comes from the Register GW; "Interworking" should be set.
* A standard Tone Mapping should be added.
* The '''"1"''' (Prefix of the first GW Object in the Register GW PBX) '''must be added''' to the called Number that goes to the Register GW; "Interworking" should be set.

[[Image: RelayGW_2Routing.jpg]]

Howto:SBC scaling for large number of channels

2016-09-05T14:14:30Z

Tru: /* Configuring the Customers regular PBX */

==Applies To==
This information applies to:

* SBC functionality on Gateways or IPVA with v12r1 or later



==More Information==

===Preamble===
With the innovaphone SBC, we provide approximately 100 - 200 concurrent Channels per Gateway or IPVA. In bigger Scenarios where a few hundred (or more) Channels are required, several Gateways can be joined to a "Load Balancing Scenario" to provide a large number of Channels.

Because a lot of SIP Provider does not support multiple registrations from many different Gateways and cannot guarantee an evenly Call distribution (Load Balancing), a dedicated SBC as SIP-Gateway for registrations is needed.

'''Please ask your SIP Provider if he provides Multiple Registrations and Load Balancing before you start with the planning of the scenario.'''

This document describes the principles how to configure a "Load Balancing Scenario" with the reference to an example.

'''Be aware that this is just an example to explain how it works; maybe it’s a little bit different in your scenario - depending on the SIP Provider! '''

===Function Principle===

The Limitation of the concurrent Channels per Gateway is based on the Media Relay Feature. If this Feature is enabled (and it’s mandatory for the SBC), the Channels are limited.

To bypass this limit, the idea is:
* to have a dedicated Gateway without Media-Relay. This acts only as Registration Gateway to the SIP Provider. Without Media Relay this Gateway can handle a very large number of calls. We call it '''"Register-GW"''' in this document.
* to use as many Gateways as needed for Media Relay. All calls should be evenly distributed on this Gateway to have a "Load Balance Scenario". We call them '''"Relay-GWs"''' in this document.

'''''Register-GW'''''

* On the "Register-GW" we need a PBX because only with the PBX we have an evenly distribution to several Gateways. Therefore the PBX must be enabled (Master) on this Gateway, but we need only two Gateway Objects in it. The first is for the registration from the Provider- SIP-Interface (on the same GW) and the second is for all registrations from the "Relay-GWs". No other object is needed.
* The SIP-Interface to the Provider is similar to the SBC of the "Common Scenario". It has two registrations, one to the SIP Provider and another to the internal PBX. Only Media relay is disabled.
* The default Routes between SIP Provider and PBX must be adapted.

'''''Relay-GWs'''''

The "Relay-GWs" are serving the Media Relay Part in this scenario. On each "Relay-GW" there are two registrations and simple routes between it.
* One registration to the "Register-GW"- PBX with Media Relay and the same Media Properties like the SIP Interface to the Provider at the "Register-GW".
* One registration to the real PBX w/o Media Relay with default settings.

[[Image:SBC_scenarios.jpg]]

==Configuration Example==
'''The following example shows how a configuration can be done, maybe it’s a little bit different in your scenario. Depending on the SIP Provider and the needed Number Mappings or Routes, there can be a lot of alternative Configurations'''

===Overview===

{| border="0"
|----
|'''1.''' On the "Register-GW " the PBX must be enabled and

two Gateway Objects with a Number must be created. In

this example we have chosen the '''Prefix "1" for calls to

the SIP Provider''' and the '''Prefix "2" for calls to the

internal PBX'''.

'''2.''' The SIP Interface must be configured without Media

Relay. The SIP Registration goes to the Provider; the

internal Registration goes to the local PBX.

'''3.''' In the Routes '''TO the "PBX of the Register-GW"''', a

leading '''"2" must be added''' to reach the opposite

GW-Object in the "PBX of the Register-GW". In the Routes

'''FROM the "PBX of the Register-GW"''', the leading '''"1"

must be cut''' because it's not needed anymore.

'''4.''' On the "Relay Gateway", two GW Interfaces must be

configured. One for the registration to the '''PBX of the

"Register-GW" with Media Relay''' and another to register

to the '''Regular PBX without Media Relay'''.

'''5.''' A Route must be created '''FROM the Regular PBX''', with

'''Tone generation and adding a leading "1"''' to reach the

opposite GW-Object in the "PBX of the Register-GW".

'''6.''' A Route must be created '''TO the Regular PBX''',

with '''cutting the leading "2"''' because it's not needed anymore.

|[[Image:ConfigurationOverview.jpg]]
|----
|}

----
===Configuring the Customers regular PBX===

'''1. Create a Trunk Object in the regular PBX'''

Of Course, in the regular PBX (where usually the Users are registered), a Trunk Object must be existing for external calls.

[[Image: RealPBX_1TrunkObject.jpg]]

===Configuring the Registration Gateway===

'''2. Enable the PBX on the Register-GW'''

On the same GW where the SBC (SIP Interface to Provider) is configured, a PBX must be created. Any System or PBX Name can be chosen because it’s normally an isolated PBX. But two Port Licenses are needed for the two Gateway registrations.

[[Image: RegisterGW_1MasterPBX.jpg]]

'''3. Create two Gateway Objects'''

Two Gateway Objects must be created on this PBX. Defaults settings can be used, but each Gateway Object must have a Number.
In this example we have chosen the '''Prefix "1" for calls to the SIP Provider''' and the '''Prefix "2" for calls to the internal PBX'''.

[[Image: RegisterGW_2PBX-GatewayObjects.jpg]]

'''4. Configure SIP Interface'''

At the SIP Interface to the Provider, nothing special must be configured, please use the Provider specific settings from the Profiles or from the Provider Documentation.
Only Media Relay must be set to "off" and the internal registration goes to the PBX on its own Gateway.

[[Image: RegisterGW_3SIP-Interface.jpg]]

'''4. Modification of the Routes'''

Following modification must be done in the Routes:
* The '''"2"''' (Prefix of the second Gateway Object in the PBX) '''must be added''' to Numbers that goes to the PBX.
* If there is a default Tone Mapping, it can be disabled or deleted.
* The leading '''"1"''' (Prefix of the first GW Object in the PBX) '''must be cut''' from each Number that comes from the PBX.

[[Image: RegisterGW_4Routing.jpg]]

=== Configuring the SBC Relay Gateways===
The following configurations are absolute identical on each Relay Gateway.

'''5. Creation of GW Interfaces'''

Two GW Interfaces must be created.
The first one is to register with the Second Gateway Object on the PBX of the "Register-GW". Here, the Media Relay must be enabled.
The second one is to register with the Trunk Object on the regular PBX. Here, the Media Relay must be disabled. All other settings (like Codecs, T.38, etc.) are depending on your requirements.

[[Image: RelayGW_1GW-Interfaces.jpg]]

'''6. Creation of the Routes'''

Routes must be created between these Gateway Interfaces:
* The leading '''"2"''' (Prefix of the second Gateway Object in the Register GW PBX) '''must be cut''' from each Number that comes from the Register GW; "Interworking" should be set.
* A standard Tone Mapping should be added.
* The '''"1"''' (Prefix of the first GW Object in the Register GW PBX) '''must be added''' to the called Number that goes to the Register GW; "Interworking" should be set.

[[Image: RelayGW_2Routing.jpg]]

Howto:SBC scaling for large number of channels

2016-09-05T14:14:05Z

Tru:

==Applies To==
This information applies to:

* SBC functionality on Gateways or IPVA with v12r1 or later



==More Information==

===Preamble===
With the innovaphone SBC, we provide approximately 100 - 200 concurrent Channels per Gateway or IPVA. In bigger Scenarios where a few hundred (or more) Channels are required, several Gateways can be joined to a "Load Balancing Scenario" to provide a large number of Channels.

Because a lot of SIP Provider does not support multiple registrations from many different Gateways and cannot guarantee an evenly Call distribution (Load Balancing), a dedicated SBC as SIP-Gateway for registrations is needed.

'''Please ask your SIP Provider if he provides Multiple Registrations and Load Balancing before you start with the planning of the scenario.'''

This document describes the principles how to configure a "Load Balancing Scenario" with the reference to an example.

'''Be aware that this is just an example to explain how it works; maybe it’s a little bit different in your scenario - depending on the SIP Provider! '''

===Function Principle===

The Limitation of the concurrent Channels per Gateway is based on the Media Relay Feature. If this Feature is enabled (and it’s mandatory for the SBC), the Channels are limited.

To bypass this limit, the idea is:
* to have a dedicated Gateway without Media-Relay. This acts only as Registration Gateway to the SIP Provider. Without Media Relay this Gateway can handle a very large number of calls. We call it '''"Register-GW"''' in this document.
* to use as many Gateways as needed for Media Relay. All calls should be evenly distributed on this Gateway to have a "Load Balance Scenario". We call them '''"Relay-GWs"''' in this document.

'''''Register-GW'''''

* On the "Register-GW" we need a PBX because only with the PBX we have an evenly distribution to several Gateways. Therefore the PBX must be enabled (Master) on this Gateway, but we need only two Gateway Objects in it. The first is for the registration from the Provider- SIP-Interface (on the same GW) and the second is for all registrations from the "Relay-GWs". No other object is needed.
* The SIP-Interface to the Provider is similar to the SBC of the "Common Scenario". It has two registrations, one to the SIP Provider and another to the internal PBX. Only Media relay is disabled.
* The default Routes between SIP Provider and PBX must be adapted.

'''''Relay-GWs'''''

The "Relay-GWs" are serving the Media Relay Part in this scenario. On each "Relay-GW" there are two registrations and simple routes between it.
* One registration to the "Register-GW"- PBX with Media Relay and the same Media Properties like the SIP Interface to the Provider at the "Register-GW".
* One registration to the real PBX w/o Media Relay with default settings.

[[Image:SBC_scenarios.jpg]]

==Configuration Example==
'''The following example shows how a configuration can be done, maybe it’s a little bit different in your scenario. Depending on the SIP Provider and the needed Number Mappings or Routes, there can be a lot of alternative Configurations'''

===Overview===

{| border="0"
|----
|'''1.''' On the "Register-GW " the PBX must be enabled and

two Gateway Objects with a Number must be created. In

this example we have chosen the '''Prefix "1" for calls to

the SIP Provider''' and the '''Prefix "2" for calls to the

internal PBX'''.

'''2.''' The SIP Interface must be configured without Media

Relay. The SIP Registration goes to the Provider; the

internal Registration goes to the local PBX.

'''3.''' In the Routes '''TO the "PBX of the Register-GW"''', a

leading '''"2" must be added''' to reach the opposite

GW-Object in the "PBX of the Register-GW". In the Routes

'''FROM the "PBX of the Register-GW"''', the leading '''"1"

must be cut''' because it's not needed anymore.

'''4.''' On the "Relay Gateway", two GW Interfaces must be

configured. One for the registration to the '''PBX of the

"Register-GW" with Media Relay''' and another to register

to the '''Regular PBX without Media Relay'''.

'''5.''' A Route must be created '''FROM the Regular PBX''', with

'''Tone generation and adding a leading "1"''' to reach the

opposite GW-Object in the "PBX of the Register-GW".

'''6.''' A Route must be created '''TO the Regular PBX''',

with '''cutting the leading "2"''' because it's not needed anymore.

|[[Image:ConfigurationOverview.jpg]]
|----
|}

===Configuring the Customers regular PBX===

'''1. Create a Trunk Object in the regular PBX'''

Of Course, in the regular PBX (where usually the Users are registered), a Trunk Object must be existing for external calls.

[[Image: RealPBX_1TrunkObject.jpg]]

===Configuring the Registration Gateway===

'''2. Enable the PBX on the Register-GW'''

On the same GW where the SBC (SIP Interface to Provider) is configured, a PBX must be created. Any System or PBX Name can be chosen because it’s normally an isolated PBX. But two Port Licenses are needed for the two Gateway registrations.

[[Image: RegisterGW_1MasterPBX.jpg]]

'''3. Create two Gateway Objects'''

Two Gateway Objects must be created on this PBX. Defaults settings can be used, but each Gateway Object must have a Number.
In this example we have chosen the '''Prefix "1" for calls to the SIP Provider''' and the '''Prefix "2" for calls to the internal PBX'''.

[[Image: RegisterGW_2PBX-GatewayObjects.jpg]]

'''4. Configure SIP Interface'''

At the SIP Interface to the Provider, nothing special must be configured, please use the Provider specific settings from the Profiles or from the Provider Documentation.
Only Media Relay must be set to "off" and the internal registration goes to the PBX on its own Gateway.

[[Image: RegisterGW_3SIP-Interface.jpg]]

'''4. Modification of the Routes'''

Following modification must be done in the Routes:
* The '''"2"''' (Prefix of the second Gateway Object in the PBX) '''must be added''' to Numbers that goes to the PBX.
* If there is a default Tone Mapping, it can be disabled or deleted.
* The leading '''"1"''' (Prefix of the first GW Object in the PBX) '''must be cut''' from each Number that comes from the PBX.

[[Image: RegisterGW_4Routing.jpg]]

=== Configuring the SBC Relay Gateways===
The following configurations are absolute identical on each Relay Gateway.

'''5. Creation of GW Interfaces'''

Two GW Interfaces must be created.
The first one is to register with the Second Gateway Object on the PBX of the "Register-GW". Here, the Media Relay must be enabled.
The second one is to register with the Trunk Object on the regular PBX. Here, the Media Relay must be disabled. All other settings (like Codecs, T.38, etc.) are depending on your requirements.

[[Image: RelayGW_1GW-Interfaces.jpg]]

'''6. Creation of the Routes'''

Routes must be created between these Gateway Interfaces:
* The leading '''"2"''' (Prefix of the second Gateway Object in the Register GW PBX) '''must be cut''' from each Number that comes from the Register GW; "Interworking" should be set.
* A standard Tone Mapping should be added.
* The '''"1"''' (Prefix of the first GW Object in the Register GW PBX) '''must be added''' to the called Number that goes to the Register GW; "Interworking" should be set.

[[Image: RelayGW_2Routing.jpg]]

Howto:SBC scaling for large number of channels

2016-09-05T14:13:42Z

Tru: /* Overview */

==Applies To==
This information applies to:

* SBC functionality on Gateways or IPVA with v12r1 or later



==More Information==

===Preamble===
With the innovaphone SBC, we provide approximately 100 - 200 concurrent Channels per Gateway or IPVA. In bigger Scenarios where a few hundred (or more) Channels are required, several Gateways can be joined to a "Load Balancing Scenario" to provide a large number of Channels.

Because a lot of SIP Provider does not support multiple registrations from many different Gateways and cannot guarantee an evenly Call distribution (Load Balancing), a dedicated SBC as SIP-Gateway for registrations is needed.

'''Please ask your SIP Provider if he provides Multiple Registrations and Load Balancing before you start with the planning of the scenario.'''

This document describes the principles how to configure a "Load Balancing Scenario" with the reference to an example.

'''Be aware that this is just an example to explain how it works; maybe it’s a little bit different in your scenario - depending on the SIP Provider! '''

===Function Principle===

The Limitation of the concurrent Channels per Gateway is based on the Media Relay Feature. If this Feature is enabled (and it’s mandatory for the SBC), the Channels are limited.

To bypass this limit, the idea is:
* to have a dedicated Gateway without Media-Relay. This acts only as Registration Gateway to the SIP Provider. Without Media Relay this Gateway can handle a very large number of calls. We call it '''"Register-GW"''' in this document.
* to use as many Gateways as needed for Media Relay. All calls should be evenly distributed on this Gateway to have a "Load Balance Scenario". We call them '''"Relay-GWs"''' in this document.

'''''Register-GW'''''

* On the "Register-GW" we need a PBX because only with the PBX we have an evenly distribution to several Gateways. Therefore the PBX must be enabled (Master) on this Gateway, but we need only two Gateway Objects in it. The first is for the registration from the Provider- SIP-Interface (on the same GW) and the second is for all registrations from the "Relay-GWs". No other object is needed.
* The SIP-Interface to the Provider is similar to the SBC of the "Common Scenario". It has two registrations, one to the SIP Provider and another to the internal PBX. Only Media relay is disabled.
* The default Routes between SIP Provider and PBX must be adapted.

'''''Relay-GWs'''''

The "Relay-GWs" are serving the Media Relay Part in this scenario. On each "Relay-GW" there are two registrations and simple routes between it.
* One registration to the "Register-GW"- PBX with Media Relay and the same Media Properties like the SIP Interface to the Provider at the "Register-GW".
* One registration to the real PBX w/o Media Relay with default settings.

[[Image:SBC_scenarios.jpg]]

==Configuration Example==
'''The following example shows how a configuration can be done, maybe it’s a little bit different in your scenario. Depending on the SIP Provider and the needed Number Mappings or Routes, there can be a lot of alternative Configurations'''

===Overview===

{| border="0"
|----
|'''1.''' On the "Register-GW " the PBX must be enabled and

two Gateway Objects with a Number must be created. In

this example we have chosen the '''Prefix "1" for calls to

the SIP Provider''' and the '''Prefix "2" for calls to the

internal PBX'''.

'''2.''' The SIP Interface must be configured without Media

Relay. The SIP Registration goes to the Provider; the

internal Registration goes to the local PBX.

'''3.''' In the Routes '''TO the "PBX of the Register-GW"''', a

leading '''"2" must be added''' to reach the opposite

GW-Object in the "PBX of the Register-GW". In the Routes

'''FROM the "PBX of the Register-GW"''', the leading '''"1"

must be cut''' because it's not needed anymore.

'''4.''' On the "Relay Gateway", two GW Interfaces must be

configured. One for the registration to the '''PBX of the

"Register-GW" with Media Relay''' and another to register

to the '''Regular PBX without Media Relay'''.

'''5.''' A Route must be created '''FROM the Regular PBX''', with

'''Tone generation and adding a leading "1"''' to reach the

opposite GW-Object in the "PBX of the Register-GW".

'''6.''' A Route must be created '''TO the Regular PBX''',

with '''cutting the leading "2"''' because it's not needed anymore.

|[[Image:ConfigurationOverview.jpg]]
|----
|}

===Configuring the Customers regular PBX===

'''1. Create a Trunk Object in the regular PBX'''

Of Course, in the regular PBX (where usually the Users are registered), a Trunk Object must be existing for external calls.

[[Image: RealPBX_1TrunkObject.jpg]]

===Configuring the Registration Gateway===

'''2. Enable the PBX on the Register-GW'''

On the same GW where the SBC (SIP Interface to Provider) is configured, a PBX must be created. Any System or PBX Name can be chosen because it’s normally an isolated PBX. But two Port Licenses are needed for the two Gateway registrations.

[[Image: RegisterGW_1MasterPBX.jpg]]

'''3. Create two Gateway Objects'''

Two Gateway Objects must be created on this PBX. Defaults settings can be used, but each Gateway Object must have a Number.
In this example we have chosen the '''Prefix "1" for calls to the SIP Provider''' and the '''Prefix "2" for calls to the internal PBX'''.

[[Image: RegisterGW_2PBX-GatewayObjects.jpg]]

'''4. Configure SIP Interface'''

At the SIP Interface to the Provider, nothing special must be configured, please use the Provider specific settings from the Profiles or from the Provider Documentation.
Only Media Relay must be set to "off" and the internal registration goes to the PBX on its own Gateway.

[[Image: RegisterGW_3SIP-Interface.jpg]]

'''4. Modification of the Routes'''

Following modification must be done in the Routes:
* The '''"2"''' (Prefix of the second Gateway Object in the PBX) '''must be added''' to Numbers that goes to the PBX.
* If there is a default Tone Mapping, it can be disabled or deleted.
* The leading '''"1"''' (Prefix of the first GW Object in the PBX) '''must be cut''' from each Number that comes from the PBX.

[[Image: RegisterGW_4Routing.jpg]]

=== Configuring the SBC Relay Gateways===
The following configurations are absolute identical on each Relay Gateway.

'''5. Creation of GW Interfaces'''

Two GW Interfaces must be created.
The first one is to register with the Second Gateway Object on the PBX of the "Register-GW". Here, the Media Relay must be enabled.
The second one is to register with the Trunk Object on the regular PBX. Here, the Media Relay must be disabled. All other settings (like Codecs, T.38, etc.) are depending on your requirements.

[[Image: RelayGW_1GW-Interfaces.jpg]]

'''6. Creation of the Routes'''

Routes must be created between these Gateway Interfaces:
* The leading '''"2"''' (Prefix of the second Gateway Object in the Register GW PBX) '''must be cut''' from each Number that comes from the Register GW; "Interworking" should be set.
* A standard Tone Mapping should be added.
* The '''"1"''' (Prefix of the first GW Object in the Register GW PBX) '''must be added''' to the called Number that goes to the Register GW; "Interworking" should be set.

[[Image: RelayGW_2Routing.jpg]]

File:ConfigurationOverview.jpg

2016-09-05T13:59:42Z

Tru:

Howto:SBC scaling for large number of channels

2016-09-05T13:59:24Z

Tru: /* Overview */

==Applies To==
This information applies to:

* SBC functionality on Gateways or IPVA with v12r1 or later



==More Information==

===Preamble===
With the innovaphone SBC, we provide approximately 100 - 200 concurrent Channels per Gateway or IPVA. In bigger Scenarios where a few hundred (or more) Channels are required, several Gateways can be joined to a "Load Balancing Scenario" to provide a large number of Channels.

Because a lot of SIP Provider does not support multiple registrations from many different Gateways and cannot guarantee an evenly Call distribution (Load Balancing), a dedicated SBC as SIP-Gateway for registrations is needed.

'''Please ask your SIP Provider if he provides Multiple Registrations and Load Balancing before you start with the planning of the scenario.'''

This document describes the principles how to configure a "Load Balancing Scenario" with the reference to an example.

'''Be aware that this is just an example to explain how it works; maybe it’s a little bit different in your scenario - depending on the SIP Provider! '''

===Function Principle===

The Limitation of the concurrent Channels per Gateway is based on the Media Relay Feature. If this Feature is enabled (and it’s mandatory for the SBC), the Channels are limited.

To bypass this limit, the idea is:
* to have a dedicated Gateway without Media-Relay. This acts only as Registration Gateway to the SIP Provider. Without Media Relay this Gateway can handle a very large number of calls. We call it '''"Register-GW"''' in this document.
* to use as many Gateways as needed for Media Relay. All calls should be evenly distributed on this Gateway to have a "Load Balance Scenario". We call them '''"Relay-GWs"''' in this document.

'''''Register-GW'''''

* On the "Register-GW" we need a PBX because only with the PBX we have an evenly distribution to several Gateways. Therefore the PBX must be enabled (Master) on this Gateway, but we need only two Gateway Objects in it. The first is for the registration from the Provider- SIP-Interface (on the same GW) and the second is for all registrations from the "Relay-GWs". No other object is needed.
* The SIP-Interface to the Provider is similar to the SBC of the "Common Scenario". It has two registrations, one to the SIP Provider and another to the internal PBX. Only Media relay is disabled.
* The default Routes between SIP Provider and PBX must be adapted.

'''''Relay-GWs'''''

The "Relay-GWs" are serving the Media Relay Part in this scenario. On each "Relay-GW" there are two registrations and simple routes between it.
* One registration to the "Register-GW"- PBX with Media Relay and the same Media Properties like the SIP Interface to the Provider at the "Register-GW".
* One registration to the real PBX w/o Media Relay with default settings.

[[Image:SBC_scenarios.jpg]]

==Configuration Example==
'''The following example shows how a configuration can be done, maybe it’s a little bit different in your scenario. Depending on the SIP Provider and the needed Number Mappings or Routes, there can be a lot of alternative Configurations'''

===Overview===

{| border="0"
|----
|[[Image:ConfigurationOverview.jpg]]
|
'''1.''' On the "Register-GW " the PBX must be enabled and two Gateway Objects with a Number must be created. In this example we have chosen the '''Prefix "1" for calls to the SIP Provider''' and the '''Prefix "2" for calls to the internal PBX'''.

'''2.''' The SIP Interface must be configured without Media Relay. The SIP Registration goes to the Provider; the internal Registration goes to the local PBX.

'''3.''' In the Routes '''TO the "PBX of the Register-GW"''', a leading '''"2" must be added''' to reach the opposite GW-Object in the "PBX of the Register-GW".
In the Routes '''FROM the "PBX of the Register-GW"''', the leading '''"1" must be cut''' because it's not needed anymore.

'''4.''' On the "Relay Gateway", two GW Interfaces must be configured. One for the registration to the '''PBX of the "Register-GW" with Media Relay''' and another to register to the '''Regular PBX without Media Relay'''.

'''5.''' A Route must be created '''FROM the Regular PBX''', with '''Tone generation and adding a leading "1"''' to reach the opposite GW-Object in the "PBX of the Register-GW".

'''6.''' A Route must be created '''TO the Regular PBX''', with '''cutting the leading "2"''' because it's not needed anymore.
|----
|}

===Configuring the Customers regular PBX===

'''1. Create a Trunk Object in the regular PBX'''

Of Course, in the regular PBX (where usually the Users are registered), a Trunk Object must be existing for external calls.

[[Image: RealPBX_1TrunkObject.jpg]]

===Configuring the Registration Gateway===

'''2. Enable the PBX on the Register-GW'''

On the same GW where the SBC (SIP Interface to Provider) is configured, a PBX must be created. Any System or PBX Name can be chosen because it’s normally an isolated PBX. But two Port Licenses are needed for the two Gateway registrations.

[[Image: RegisterGW_1MasterPBX.jpg]]

'''3. Create two Gateway Objects'''

Two Gateway Objects must be created on this PBX. Defaults settings can be used, but each Gateway Object must have a Number.
In this example we have chosen the '''Prefix "1" for calls to the SIP Provider''' and the '''Prefix "2" for calls to the internal PBX'''.

[[Image: RegisterGW_2PBX-GatewayObjects.jpg]]

'''4. Configure SIP Interface'''

At the SIP Interface to the Provider, nothing special must be configured, please use the Provider specific settings from the Profiles or from the Provider Documentation.
Only Media Relay must be set to "off" and the internal registration goes to the PBX on its own Gateway.

[[Image: RegisterGW_3SIP-Interface.jpg]]

'''4. Modification of the Routes'''

Following modification must be done in the Routes:
* The '''"2"''' (Prefix of the second Gateway Object in the PBX) '''must be added''' to Numbers that goes to the PBX.
* If there is a default Tone Mapping, it can be disabled or deleted.
* The leading '''"1"''' (Prefix of the first GW Object in the PBX) '''must be cut''' from each Number that comes from the PBX.

[[Image: RegisterGW_4Routing.jpg]]

=== Configuring the SBC Relay Gateways===
The following configurations are absolute identical on each Relay Gateway.

'''5. Creation of GW Interfaces'''

Two GW Interfaces must be created.
The first one is to register with the Second Gateway Object on the PBX of the "Register-GW". Here, the Media Relay must be enabled.
The second one is to register with the Trunk Object on the regular PBX. Here, the Media Relay must be disabled. All other settings (like Codecs, T.38, etc.) are depending on your requirements.

[[Image: RelayGW_1GW-Interfaces.jpg]]

'''6. Creation of the Routes'''

Routes must be created between these Gateway Interfaces:
* The leading '''"2"''' (Prefix of the second Gateway Object in the Register GW PBX) '''must be cut''' from each Number that comes from the Register GW; "Interworking" should be set.
* A standard Tone Mapping should be added.
* The '''"1"''' (Prefix of the first GW Object in the Register GW PBX) '''must be added''' to the called Number that goes to the Register GW; "Interworking" should be set.

[[Image: RelayGW_2Routing.jpg]]

Howto:SBC scaling for large number of channels

2016-09-05T12:17:47Z

Tru:

==Applies To==
This information applies to:

* SBC functionality on Gateways or IPVA with v12r1 or later



==More Information==

===Preamble===
With the innovaphone SBC, we provide approximately 100 - 200 concurrent Channels per Gateway or IPVA. In bigger Scenarios where a few hundred (or more) Channels are required, several Gateways can be joined to a "Load Balancing Scenario" to provide a large number of Channels.

Because a lot of SIP Provider does not support multiple registrations from many different Gateways and cannot guarantee an evenly Call distribution (Load Balancing), a dedicated SBC as SIP-Gateway for registrations is needed.

'''Please ask your SIP Provider if he provides Multiple Registrations and Load Balancing before you start with the planning of the scenario.'''

This document describes the principles how to configure a "Load Balancing Scenario" with the reference to an example.

'''Be aware that this is just an example to explain how it works; maybe it’s a little bit different in your scenario - depending on the SIP Provider! '''

===Function Principle===

The Limitation of the concurrent Channels per Gateway is based on the Media Relay Feature. If this Feature is enabled (and it’s mandatory for the SBC), the Channels are limited.

To bypass this limit, the idea is:
* to have a dedicated Gateway without Media-Relay. This acts only as Registration Gateway to the SIP Provider. Without Media Relay this Gateway can handle a very large number of calls. We call it '''"Register-GW"''' in this document.
* to use as many Gateways as needed for Media Relay. All calls should be evenly distributed on this Gateway to have a "Load Balance Scenario". We call them '''"Relay-GWs"''' in this document.

'''''Register-GW'''''

* On the "Register-GW" we need a PBX because only with the PBX we have an evenly distribution to several Gateways. Therefore the PBX must be enabled (Master) on this Gateway, but we need only two Gateway Objects in it. The first is for the registration from the Provider- SIP-Interface (on the same GW) and the second is for all registrations from the "Relay-GWs". No other object is needed.
* The SIP-Interface to the Provider is similar to the SBC of the "Common Scenario". It has two registrations, one to the SIP Provider and another to the internal PBX. Only Media relay is disabled.
* The default Routes between SIP Provider and PBX must be adapted.

'''''Relay-GWs'''''

The "Relay-GWs" are serving the Media Relay Part in this scenario. On each "Relay-GW" there are two registrations and simple routes between it.
* One registration to the "Register-GW"- PBX with Media Relay and the same Media Properties like the SIP Interface to the Provider at the "Register-GW".
* One registration to the real PBX w/o Media Relay with default settings.

[[Image:SBC_scenarios.jpg]]

==Configuration Example==
'''The following example shows how a configuration can be done, maybe it’s a little bit different in your scenario. Depending on the SIP Provider and the needed Number Mappings or Routes, there can be a lot of alternative Configurations'''

===Overview===

{| border="1"
|----
|TEXT1
|-----
|OK
|-----
|OK
|----
|TEXT2
|OK
|OK
|}

===Configuring the Customers regular PBX===

'''1. Create a Trunk Object in the regular PBX'''

Of Course, in the regular PBX (where usually the Users are registered), a Trunk Object must be existing for external calls.

[[Image: RealPBX_1TrunkObject.jpg]]

===Configuring the Registration Gateway===

'''2. Enable the PBX on the Register-GW'''

On the same GW where the SBC (SIP Interface to Provider) is configured, a PBX must be created. Any System or PBX Name can be chosen because it’s normally an isolated PBX. But two Port Licenses are needed for the two Gateway registrations.

[[Image: RegisterGW_1MasterPBX.jpg]]

'''3. Create two Gateway Objects'''

Two Gateway Objects must be created on this PBX. Defaults settings can be used, but each Gateway Object must have a Number.
In this example we have chosen the '''Prefix "1" for calls to the SIP Provider''' and the '''Prefix "2" for calls to the internal PBX'''.

[[Image: RegisterGW_2PBX-GatewayObjects.jpg]]

'''4. Configure SIP Interface'''

At the SIP Interface to the Provider, nothing special must be configured, please use the Provider specific settings from the Profiles or from the Provider Documentation.
Only Media Relay must be set to "off" and the internal registration goes to the PBX on its own Gateway.

[[Image: RegisterGW_3SIP-Interface.jpg]]

'''4. Modification of the Routes'''

Following modification must be done in the Routes:
* The '''"2"''' (Prefix of the second Gateway Object in the PBX) '''must be added''' to Numbers that goes to the PBX.
* If there is a default Tone Mapping, it can be disabled or deleted.
* The leading '''"1"''' (Prefix of the first GW Object in the PBX) '''must be cut''' from each Number that comes from the PBX.

[[Image: RegisterGW_4Routing.jpg]]

=== Configuring the SBC Relay Gateways===
The following configurations are absolute identical on each Relay Gateway.

'''5. Creation of GW Interfaces'''

Two GW Interfaces must be created.
The first one is to register with the Second Gateway Object on the PBX of the "Register-GW". Here, the Media Relay must be enabled.
The second one is to register with the Trunk Object on the regular PBX. Here, the Media Relay must be disabled. All other settings (like Codecs, T.38, etc.) are depending on your requirements.

[[Image: RelayGW_1GW-Interfaces.jpg]]

'''6. Creation of the Routes'''

Routes must be created between these Gateway Interfaces:
* The leading '''"2"''' (Prefix of the second Gateway Object in the Register GW PBX) '''must be cut''' from each Number that comes from the Register GW; "Interworking" should be set.
* A standard Tone Mapping should be added.
* The '''"1"''' (Prefix of the first GW Object in the Register GW PBX) '''must be added''' to the called Number that goes to the Register GW; "Interworking" should be set.

[[Image: RelayGW_2Routing.jpg]]

Howto:SBC scaling for large number of channels

2016-09-05T12:10:26Z

Tru:

==Applies To==
This information applies to:

* SBC functionality on Gateways or IPVA with v12r1 or later



==More Information==

===Preamble===
With the innovaphone SBC, we provide approximately 100 - 200 concurrent Channels per Gateway or IPVA. In bigger Scenarios where a few hundred (or more) Channels are required, several Gateways can be joined to a "Load Balancing Scenario" to provide a large number of Channels.

Because a lot of SIP Provider does not support multiple registrations from many different Gateways and cannot guarantee an evenly Call distribution (Load Balancing), a dedicated SBC as SIP-Gateway for registrations is needed.

'''Please ask your SIP Provider if he provides multiple registrations and Load Balancing before you start with the planning of such a scenario'''

This document describes the principles how to configure a "Load Balancing Scenario" with the reference to an example.

'''Be aware that this is just an example to explain how it works; maybe it’s a little bit different in your scenario - depending on the SIP Provider! '''

===Function Principle===

The Limitation of the concurrent Channels per Gateway is based on the Media Relay Feature. If this Feature is enabled (and it’s mandatory for the SBC), the Channels are limited.

To bypass this limit, the idea is:
* to have a dedicated Gateway without Media-Relay. This acts only as Registration Gateway to the SIP Provider. Without Media Relay this Gateway can handle a very large number of calls. We call it '''"Register-GW"''' in this document.
* to use as many Gateways as needed for Media Relay. All calls should be evenly distributed on this Gateway to have a "Load Balance Scenario". We call them '''"Relay-GWs"''' in this document.

'''''Register-GW'''''

* On the "Register-GW" we need a PBX because only with the PBX we have an evenly distribution to several Gateways. Therefore the PBX must be enabled (Master) on this Gateway, but we need only two Gateway Objects in it. The first is for the registration from the Provider- SIP-Interface (on the same GW) and the second is for all registrations from the "Relay-GWs". No other object is needed.
* The SIP-Interface to the Provider is similar to the SBC of the "Common Scenario". It has two registrations, one to the SIP Provider and another to the internal PBX. Only Media relay is disabled.
* The default Routes between SIP Provider and PBX must be adapted.

'''''Relay-GWs'''''

The "Relay-GWs" are serving the Media Relay Part in this scenario. On each "Relay-GW" there are two registrations and simple routes between it.
* One registration to the "Register-GW"- PBX with Media Relay and the same Media Properties like the SIP Interface to the Provider at the "Register-GW".
* One registration to the real PBX w/o Media Relay with default settings.

[[Image:SBC_scenarios.jpg]]

==Configuration Example==
'''The following example shows how a configuration can be done, maybe it’s a little bit different in your scenario. Depending on the SIP Provider and the needed Number Mappings or Routes, there can be a lot of alternative Configurations'''

===Overview===

{| border="1"
!Tested feature
!Result
|----
|'''Call can be put on hold'''
|OK
|----
|Held end hears music on hold / announcement from PBX
|OK
|}

{| border="1"
!Tested feature
!Voice Ok?
!MoH Ok?
|----
|inno1 calls inno2. inno2 transfers to PSTN-phone.
|OK
|OK
|----
|inno1 calls PSTN-phone. inno1 transfers to inno2.
|OK
|OK
|----
|inno1 calls PSTN-phone. PSTN-phone transfers to inno2.
|OK
|OK
|----
|PSTN-phone calls inno1. inno1 transfers to inno2.
|OK
|OK
|----
|PSTN-phone calls inno1. PSTN-phone transfers to inno2.
|OK
|OK
|----
|PSTN-phone calls inno1. inno1 transfers to other PSTN-phone-2.
|OK
|OK
|}

===Configuring the Customers regular PBX===

'''1. Create a Trunk Object in the regular PBX'''

Of Course, in the regular PBX (where usually the Users are registered), a Trunk Object must be existing for external calls.

[[Image: RealPBX_1TrunkObject.jpg]]

===Configuring the Registration Gateway===

'''2. Enable the PBX on the Register-GW'''

On the same GW where the SBC (SIP Interface to Provider) is configured, a PBX must be created. Any System or PBX Name can be chosen because it’s normally an isolated PBX. But two Port Licenses are needed for the two Gateway registrations.

[[Image: RegisterGW_1MasterPBX.jpg]]

'''3. Create two Gateway Objects'''

Two Gateway Objects must be created on this PBX. Defaults settings can be used, but each Gateway Object must have a Number.
In this example we have chosen the '''Prefix "1" for calls to the SIP Provider''' and the '''Prefix "2" for calls to the internal PBX'''.

[[Image: RegisterGW_2PBX-GatewayObjects.jpg]]

'''4. Configure SIP Interface'''

At the SIP Interface to the Provider, nothing special must be configured, please use the Provider specific settings from the Profiles or from the Provider Documentation.
Only Media Relay must be set to "off" and the internal registration goes to the PBX on its own Gateway.

[[Image: RegisterGW_3SIP-Interface.jpg]]

'''4. Modification of the Routes'''

Following modification must be done in the Routes:
* The '''"2"''' (Prefix of the second Gateway Object in the PBX) '''must be added''' to Numbers that goes to the PBX.
* If there is a default Tone Mapping, it can be disabled or deleted.
* The leading '''"1"''' (Prefix of the first GW Object in the PBX) '''must be cut''' from each Number that comes from the PBX.

[[Image: RegisterGW_4Routing.jpg]]

=== Configuring the SBC Relay Gateways===
The following configurations are absolute identical on each Relay Gateway.

'''5. Creation of GW Interfaces'''

Two GW Interfaces must be created.
The first one is to register with the Second Gateway Object on the PBX of the "Register-GW". Here, the Media Relay must be enabled.
The second one is to register with the Trunk Object on the regular PBX. Here, the Media Relay must be disabled. All other settings (like Codecs, T.38, etc.) are depending on your requirements.

[[Image: RelayGW_1GW-Interfaces.jpg]]

'''6. Creation of the Routes'''

Routes must be created between these Gateway Interfaces:
* The leading '''"2"''' (Prefix of the second Gateway Object in the Register GW PBX) '''must be cut''' from each Number that comes from the Register GW; "Interworking" should be set.
* A standard Tone Mapping should be added.
* The '''"1"''' (Prefix of the first GW Object in the Register GW PBX) '''must be added''' to the called Number that goes to the Register GW; "Interworking" should be set.

[[Image: RelayGW_2Routing.jpg]]

Howto:SBC scaling for large number of channels

2016-09-02T13:26:32Z

Tru: /* Configuring the Registration Gateway */

==Applies To==
This information applies to:

* SBC functionality on Gateways or IPVA with v12r1 or later



==More Information==

===Preamble===
With the innovaphone SBC, we provide approximately 100 - 200 concurrent Channels per Gateway or IPVA. In bigger Scenarios where a few hundred (or more) Channels are required, several Gateways can be joined to a "Load Balancing Scenario" to provide a large number of Channels.

Also, in most scenarios an additional and dedicated SBC as SIP -Gateway to the Provider is needed (with or w/o registrations), because most of the SIP Providers accepts only one registration.

This document describes the principles how to configure such a "Load Balancing Scenario" with the reference to an example.

'''Be aware that this is just an example to explain how it works; maybe it’s a little bit different in your scenario depending on the SIP Provider! '''

===Function Principle===

The Limitation of the concurrent Channels per Gateway is based on the Media Relay Feature. If this Feature is enabled (and it’s mandatory for the SBC), the Channels are limited.

To bypass this limit, the idea is:
* to have a dedicated Gateway without Media-Relay. This acts only as Registration Gateway to the SIP Provider. Without Media Relay this Gateway can handle a very large number of calls. We call it '''"Register-GW"''' in this document.
* to use as many Gateways as needed for Media Relay. All calls should be evenly distributed on this Gateway to have a "Load Balance Scenario". We call them '''"Relay-GWs"''' in this document.

'''''Register-GW'''''

* On the "Register-GW" we need a PBX because only with the PBX we have an evenly distribution to several Gateways. Therefore the PBX must be enabled (Master) on this Gateway, but we need only two Gateway Objects in it. The first is for the registration from the Provider- SIP-Interface (on the same GW) and the second is for all registrations from the "Relay-GWs". No other object is needed.
* The SIP-Interface to the Provider is similar to the SBC of the "Common Scenario". It has two registrations, one to the SIP Provider and another to the internal PBX. Only Media relay is disabled.
* The default Routes between SIP Provider and PBX must be adapted.

'''''Relay-GWs'''''

The "Relay-GWs" are serving the Media Relay Part in this scenario. On each "Relay-GW" there are two registrations and simple routes between it.
* One registration to the "Register-GW"- PBX with Media Relay and the same Media Properties like the SIP Interface to the Provider at the "Register-GW".
* One registration to the real PBX w/o Media Relay with default settings.

[[Image:SBC_scenarios.jpg]]

==Configuration Example==
'''The following example shows how a configuration can be done, maybe it’s a little bit different in your scenario. Depending on the SIP Provider and the needed Number Mappings or Routes, there can be a lot of alternative Configurations'''

===Configuring the Customers regular PBX===

'''1. Create a Trunk Object in the regular PBX'''

Of Course, in the regular PBX (where usually the Users are registered), a Trunk Object must be existing for external calls.

[[Image: RealPBX_1TrunkObject.jpg]]

===Configuring the Registration Gateway===

'''2. Enable the PBX on the Register-GW'''

On the same GW where the SBC (SIP Interface to Provider) is configured, a PBX must be created. Any System or PBX Name can be chosen because it’s normally an isolated PBX. But two Port Licenses are needed for the two Gateway registrations.

[[Image: RegisterGW_1MasterPBX.jpg]]

'''3. Create two Gateway Objects'''

Two Gateway Objects must be created on this PBX. Defaults settings can be used, but each Gateway Object must have a Number.
In this example we have chosen the '''Prefix "1" for calls to the SIP Provider''' and the '''Prefix "2" for calls to the internal PBX'''.

[[Image: RegisterGW_2PBX-GatewayObjects.jpg]]

'''4. Configure SIP Interface'''

At the SIP Interface to the Provider, nothing special must be configured, please use the Provider specific setting from the Profiles or from the Provider Documentation.
Only Media Relay must be set to "off" and the internal registration goes to the PBX on its own Gateway.

[[Image: RegisterGW_3SIP-Interface.jpg]]

'''4. Modification of the Routes'''

Following modification must be done in the Routes:
* The '''"2"''' (Prefix of the second Gateway Object in the PBX) '''must be added''' to Numbers that goes to the PBX.
* If there is a default Tone Mapping, it can be disabled or deleted.
* The leading '''"1"''' (Prefix of the first GW Object in the PBX) '''must be cut''' from each Number that comes from the PBX.

[[Image: RegisterGW_4Routing.jpg]]

=== Configuring the SBC Relay Gateways===
The following configurations are absolute identical on each Relay Gateway.

'''5. Creation of GW Interfaces'''

Two GW Interfaces must be created.
The first one is to register with the Second Gateway Object on the PBX of the "Register-GW". Here, the Media Relay must be enabled.
The second one is to register with the Trunk Object on the regular PBX. Here, the Media Relay must be disabled. All other settings (like Codecs, T.38, etc.) are depending on your requirements.

[[Image: RelayGW_1GW-Interfaces.jpg]]

'''6. Creation of the Routes'''

Routes must be created between these Gateway Interfaces:
* The leading '''"2"''' (Prefix of the second Gateway Object in the Register GW PBX) '''must be cut''' from each Number that comes from the Register GW.
* A standard Tone Mapping should be added.
* The '''"1"''' (Prefix of the first GW Object in the Register GW PBX) '''must be added''' to the called Number that goes to the Register GW.

[[Image: RelayGW_2Routing.jpg]]

Howto:SBC scaling for large number of channels

2016-09-02T12:50:52Z

Tru:

==Applies To==
This information applies to:

* SBC functionality on Gateways or IPVA with v12r1 or later



==More Information==

===Preamble===
With the innovaphone SBC, we provide approximately 100 - 200 concurrent Channels per Gateway or IPVA. In bigger Scenarios where a few hundred (or more) Channels are required, several Gateways can be joined to a "Load Balancing Scenario" to provide a large number of Channels.

Also, in most scenarios an additional and dedicated SBC as SIP -Gateway to the Provider is needed (with or w/o registrations), because most of the SIP Providers accepts only one registration.

This document describes the principles how to configure such a "Load Balancing Scenario" with the reference to an example.

'''Be aware that this is just an example to explain how it works; maybe it’s a little bit different in your scenario depending on the SIP Provider! '''

===Function Principle===

The Limitation of the concurrent Channels per Gateway is based on the Media Relay Feature. If this Feature is enabled (and it’s mandatory for the SBC), the Channels are limited.

To bypass this limit, the idea is:
* to have a dedicated Gateway without Media-Relay. This acts only as Registration Gateway to the SIP Provider. Without Media Relay this Gateway can handle a very large number of calls. We call it '''"Register-GW"''' in this document.
* to use as many Gateways as needed for Media Relay. All calls should be evenly distributed on this Gateway to have a "Load Balance Scenario". We call them '''"Relay-GWs"''' in this document.

'''''Register-GW'''''

* On the "Register-GW" we need a PBX because only with the PBX we have an evenly distribution to several Gateways. Therefore the PBX must be enabled (Master) on this Gateway, but we need only two Gateway Objects in it. The first is for the registration from the Provider- SIP-Interface (on the same GW) and the second is for all registrations from the "Relay-GWs". No other object is needed.
* The SIP-Interface to the Provider is similar to the SBC of the "Common Scenario". It has two registrations, one to the SIP Provider and another to the internal PBX. Only Media relay is disabled.
* The default Routes between SIP Provider and PBX must be adapted.

'''''Relay-GWs'''''

The "Relay-GWs" are serving the Media Relay Part in this scenario. On each "Relay-GW" there are two registrations and simple routes between it.
* One registration to the "Register-GW"- PBX with Media Relay and the same Media Properties like the SIP Interface to the Provider at the "Register-GW".
* One registration to the real PBX w/o Media Relay with default settings.

[[Image:SBC_scenarios.jpg]]

==Configuration Example==
'''The following example shows how a configuration can be done, maybe it’s a little bit different in your scenario. Depending on the SIP Provider and the needed Number Mappings or Routes, there can be a lot of alternative Configurations'''

===Configuring the Customers regular PBX===

'''1. Create a Trunk Object in the regular PBX'''

Of Course, in the regular PBX (where usually the Users are registered), a Trunk Object must be existing for external calls.

[[Image: RealPBX_1TrunkObject.jpg]]

===Configuring the Registration Gateway===

'''2. Enable the PBX on the Register-GW'''

On the same GW where the SBC (SIP Interface to Provider) is configured, a PBX must be created. Any System or PBX Name can be chosen because it’s normally an isolated PBX. But two Port Licenses are needed for the two Gateway registrations.

[[Image: RegisterGW_1MasterPBX.jpg]]

'''3. Create two Gateway Objects'''

Two Gateway Objects must be created on this PBX. Defaults settings can be used, but each Gateway Object must have a Number.
In this example we have chosen the '''Prefix "1" for calls to the SIP Provider''' and the '''Prefix "2" for calls to the internal PBX'''.

[[Image: RegisterGW_2PBX-GatewayObjects.jpg]]

'''4. Configure SIP Interface'''

At the SIP Interface to the Provider, nothing special must be configured, please use the Provider specific setting from the Profiles or from the Provider Documentation.
Only Media Relay must be set to "off" and the internal registration goes to the PBX on its own Gateway.

[[Image: RegisterGW_3SIP-Interface.jpg]]

'''4. Modification of the Routes'''

Following modification must be done in the Routes:
* The '''"2"''' (Prefix of the second Gateway Object in the PBX) '''must be added''' to Numbers that goes to the PBX.
* If there is a default Tone Mapping, it can be disabled or deleted.
* The leading '''"1"''' (Prefix of the first GW Object in the PBX) '''must be cut''' from each Number that comes from the PBX.

[[Image: RegisterGW_4Routing.jpg]]

=== Configuring the SBC Relay Gateways===
The following configurations are absolute identical on each Relay Gateway.

'''5. Creation of GW Interfaces'''

Two GW Interfaces must be created.
The first one is to register with the Second Gateway Object on the PBX of the "Register-GW". Here, the Media Relay must be enabled.
The second one is to register with the Trunk Object on the regular PBX. Here, the Media Relay must be disabled. All other settings (like Codecs, T.38, etc.) are depending on your requirements.

[[Image: RelayGW_1GW-Interfaces.jpg]]

'''6. Creation of the Routes'''

Routes must be created between these Gateway Interfaces:
* The leading '''"2"''' (Prefix of the second Gateway Object in the Register GW PBX) '''must be cut''' from each Number that comes from the Register GW.
* A standard Tone Mapping should be added.
* The '''"1"''' (Prefix of the first GW Object in the Register GW PBX) '''must be added''' to the called Number that goes to the Register GW.

[[Image: RelayGW_2Routing.jpg]]

Howto:SBC scaling for large number of channels

2016-09-02T12:22:01Z

Tru:

==Applies To==
This information applies to

* SBC functionality on Gateways or IPVA with v12r1 or later



==More Information==

===Preamble===
With the innovaphone SBC, we provide approximately 100 - 200 concurrent Channels per Gateway or IPVA. In bigger Scenarios where a few hundred (or more) Channels are required, several Gateways can be joined to a "Load Balancing Scenario" to provide a large number of Channels.

Also, in most scenarios an additional and dedicated SBC as SIP -Gateway to the Provider is needed (with or w/o registrations), because the most part of SIP Providers accept only one counterpart.

This document describes the principles how to configure such a "Load Balancing Scenario" with reference to an example.

'''Be aware that this is just an example to explain how it works; maybe it’s a little bit different in your scenarios depending on the SIP Provider!'''

===Function Principle===

The Limitation of the concurrent Channels per Gateway is based on the Media Relay Feature. If this Feature is enabled (and it’s mandatory for the SBC), the Channels are limited.

To bypass this limit, the idea is:
* to have a dedicated Gateway without Media-Relay. This acts only as Registration Gateway to the SIP Provider. Without Media Relay this Gateway can handle a very large number of calls. We call it '''"Register-GW"''' in this document.
* to use as many Gateways as needed for Media Relay. All calls should be evenly distributed on this Gateway to have a "Load Balance Scenario". We call them '''"Relay-GWs"''' in this document.

'''''Register-GW'''''

* On the "Register-GW" we need a PBX because only with the PBX we have an evenly distribution to several Gateways. Therefore the PBX must be enabled (Master) on this Gateway, but we need only two Gateway Objects in it. The first is for the registration from the Provider- SIP-Interface (on the same GW) and the second is for all registrations from the "Relay-GWs". No other object is needed.
* The SIP-Interface to the Provider is similar to the SBC of the "Common Scenario". It has two registrations, one to the SIP Provider and another to the internal PBX. Only Media relay is disabled.
* The default Routes between SIP Provider and PBX must be adapted.

'''''Relay-GWs'''''

The "Relay-GWs" are serving the Media Relay Part in this scenario. On each "Relay-GW" there are two registrations and simple routes between it.
* One registration to the "Register-GW"- PBX with Media Relay and the same SDP settings like the SIP Interface to the Provider.
* One registration to the real PBX w/o Media Relay with default settings.

[[Image:SBC_scenarios.jpg]]

==Configuration Example==
'''The following example shows how a configuration can be done, maybe it’s a little bit different in your scenario. Depending on the SIP Provider and the needed Number Mappings or Routes, there can be a lot of alternative Configurations'''

===Configuring the Customers regular PBX===

'''1. Create a Trunk Object in the regular PBX'''

Of Course, in the regular PBX (where usually the Users are registered), a Trunk Object must be existing with the Number for External calls.

[[Image: RealPBX_1TrunkObject.jpg]]

===Configuring the Registration Gateway===

'''2. Enable the PBX on the Register-GW'''

On the same GW where the SBC (SIP Interface to Provider) is configured, a PBX must be created. Any System or PBX Name can be chosen because it’s normally an isolated PBX. But two Port Licenses are needed for the two Gateway registrations.

[[Image: RegisterGW_1MasterPBX.jpg]]

'''3. Create two Gateway Objects'''

On this PBX two Gateway Objects must be created. Defaults settings can be used, but each Gateway Object must have a Number.
In this example we have chosen the Prefix "1" for calls to the SIP Provider and the Prefix "2" for calls to the internal PBX.

[[Image: RegisterGW_2PBX-GatewayObjects.jpg]]

'''4. Configure SIP Interface'''

At the SIP Interface to the Provider, nothing special must be configured, please use the Provider specific setting from the Profiles or from the Provider Documentation.
Only Media Relay must be set to "off" and the internal registration goes to the PBX on its own Gateway.

[[Image: RegisterGW_3SIP-Interface.jpg]]

'''4. Modification of the Routes'''

Following modification must be done in the Routes
* The '''"2"''' (Prefix of the second Gateway Object in the PBX) '''must be added''' before each called Number that goes to the PBX.
* If there is a default Tone Mapping, it can be disabled or deleted.
* The '''"1"''' (Prefix of the first GW Object in the PBX) '''must be cut''' before each called Number that comes from the PBX.

[[Image: RegisterGW_4Routing.jpg]]

=== Configuring the SBC Relay Gateways===
The following configurations are absolute identical on each Relay Gateway.

'''5. Creation of GW Interfaces'''

Two

[[Image: RelayGW_1GW-Interfaces.jpg]]

'''6. Creation of the Routes'''

Following

[[Image: RelayGW_2Routing.jpg]]

Howto:SBC scaling for large number of channels

2016-09-02T12:10:15Z

Tru:

==Applies To==
This information applies to

* SBC functionality on Gateways or IPVA with v12r1 or later



==More Information==

===Preamble===
With the innovaphone SBC, we provide approximately 100 - 200 concurrent Channels per Gateway or IPVA. In bigger Scenarios where a few hundred (or more) Channels are required, several Gateways can be joined to a "Load Balancing Scenario" to provide a large number of Channels.

Also, in most scenarios an additional and dedicated SBC as SIP -Gateway to the Provider is needed (with or w/o registrations), because the most part of SIP Providers accept only one counterpart.

This document describes the principles how to configure such a "Load Balancing Scenario" with reference to an example.

'''Be aware that this is just an example to explain how it works; maybe it’s a little bit different in your scenarios depending on the SIP Provider!'''

===Function Principle===

The Limitation of the concurrent Channels per Gateway is based on the Media Relay Feature. If this Feature is enabled (and it’s mandatory for the SBC), the Channels are limited.

To bypass this limit, the idea is:
* to have a dedicated Gateway without Media-Relay. This acts only as Registration Gateway to the SIP Provider. Without Media Relay this Gateway can handle a very large number of calls. We call it '''"Register-GW"''' in this document.
* to use as many Gateways as needed for Media Relay. All calls should be evenly distributed on this Gateway to have a "Load Balance Scenario". We call them '''"Relay-GWs"''' in this document.

'''''Register-GW'''''

* On the "Register-GW" we need a PBX because only with the PBX we have an evenly distribution to several Gateways. Therefore the PBX must be enabled (Master) on this Gateway, but we need only two Gateway Objects in it. The first is for the registration from the Provider- SIP-Interface (on the same GW) and the second is for all registrations from the "Relay-GWs". No other object is needed.
* The SIP-Interface to the Provider is similar to the SBC of the "Common Scenario". It has two registrations, one to the SIP Provider and another to the internal PBX. Only Media relay is disabled.
* The default Routes between SIP Provider and PBX must be adapted.

'''''Relay-GWs'''''

The "Relay-GWs" are serving the Media Relay Part in this scenario. On each "Relay-GW" there are two registrations and simple routes between it.
* One registration to the "Register-GW"- PBX with Media Relay and the same SDP settings like the SIP Interface to the Provider.
* One registration to the real PBX w/o Media Relay with default settings.

[[Image:SBC_scenarios.jpg]]

==Configuration Example==
'''The following example shows how a configuration can be done, maybe it’s a little bit different in your scenario. Depending on the SIP Provider and the needed Number Mappings or Routes, there can be a lot of alternative Configurations'''

===Configuring the Customers regular PBX===

'''1. Create a Trunk Object in the regular PBX'''

Of Course, in the regular PBX (where usually the Users are registered), a Trunk Object must be existing with the Number for External calls.
[[Image: RealPBX_1TrunkObject.jpg]]

===Configuring the Registration Gateway===

'''2. Enable the PBX on the Register-GW'''

On the same GW where the SBC (SIP Interface to Provider) is configured, a PBX must be created. Any System or PBX Name can be chosen because it’s normally an isolated PBX. But two Port Licenses are needed for the two Gateway registrations.
[[Image: RegisterGW_1MasterPBX.jpg]]

'''3. Create two Gateway Objects'''

On this PBX two Gateway Objects must be created. Defaults settings can be used, but each Gateway Object must have a Number.
In this example we have chosen the Prefix "1" for calls to the SIP Provider and the Prefix "2" for calls to the internal PBX.
[[Image: RegisterGW_2PBX-GatewayObjects.jpg]]

'''4. Configure SIP Interface'''

At the SIP Interface to the Provider, nothing special must be configured, please use the Provider specific setting from the Profiles or from the Provider Documentation.
Only Media Relay must be set to "off" and the internal registration goes to the PBX on its own Gateway.
[[Image: RegisterGW_3SIP-Interface.jpg]]

'''4. Modification of the Routes'''

Following modification must be done in the Routes
* The '''"2"''' (Prefix of the second Gateway Object in the PBX) '''must be added''' before each called Number that goes to the PBX.
* If there is a default Tone Mapping, it can be disabled or deleted.
* The '''"1"''' (Prefix of the first GW Object in the PBX) '''must be cut''' before each called Number that comes from the PBX.
[[Image: RegisterGW_4Routing.jpg]]

=== Configuring the SBC Relay Gateways===

[[Image: RelayGW_1GW-Interfaces.jpg]]

[[Image: RelayGW_2Routing.jpg]]

File:RelayGW 2Routing.jpg

2016-09-02T11:38:28Z

Tru:

File:RelayGW 1GW-Interfaces.jpg

2016-09-02T11:38:15Z

Tru:

File:RegisterGW 4Routing.jpg

2016-09-02T11:38:00Z

Tru:

File:RegisterGW 3SIP-Interface.jpg

2016-09-02T11:37:41Z

Tru:

File:RegisterGW 2PBX-GatewayObjects.jpg

2016-09-02T11:37:23Z

Tru:

File:RegisterGW 1MasterPBX.jpg

2016-09-02T11:37:01Z

Tru:

File:RealPBX 1TrunkObject.jpg

2016-09-02T11:35:51Z

Tru:

Howto:SBC scaling for large number of channels

2016-09-02T11:33:57Z

Tru:

File:RealPBX TrunkObject.jpg

2016-09-02T09:33:30Z

Tru: In the customer Real PBX,

In the customer Real PBX,

Howto:SBC scaling for large number of channels

2016-09-02T09:32:54Z

Tru:

Howto:SBC scaling for large number of channels

2016-09-02T09:32:10Z

Tru:

Howto:SBC scaling for large number of channels

2016-09-01T14:01:14Z

Tru:

Howto:SBC scaling for large number of channels

2016-09-01T14:00:18Z

Tru:

File:SBC scenarios.jpg

2016-09-01T13:56:50Z

Tru:

Howto:SBC scaling for large number of channels

2016-09-01T13:56:29Z

Tru: New page: ==Applies To== This information applies to * SBC functionality on Gateways or IPVA with v12r1 or later <!-- Keywords: SBC, Session Border Controller, scale, scaling, large, number, chan...

File:Outlook.jpg

2016-08-16T16:21:53Z

Tru:

File:Thunderbird.jpg

2016-08-16T16:21:27Z

Tru:

Howto:Faxserver with Mailclients

2016-08-16T16:21:14Z

Tru:

'''These are examples howto setup the Mail-Clients for direct Faxserver access.'''

'''Example for Thunderbird:'''

[[Image:Thunderbird.jpg]]

----

'''Example for Outlook:'''

[[Image:Outlook.jpg]]

Howto:Faxserver with Mailclients

2016-08-16T16:17:50Z

Tru:

These are examples howto setup the Mail-Clients for direct Faxserver access.

Example for Thunderbird:

[[Image:Example.jpg]]

Example for Outlook:

[[Image:Example.jpg]]

Howto:Faxserver with Mailclients

2016-08-16T16:13:56Z

Tru: New page: These are examples howto setup the Mail-Clients for direct Faxserver access. Example for Thunderbird: Image:Example.jpg Example for Outlook: Image:Example.jpg

These are examples howto setup the Mail-Clients for direct Faxserver access.

Example for Thunderbird:
[[Image:Example.jpg]]

Example for Outlook:
[[Image:Example.jpg]]