Courseware:IT Plus - The Reports App

This book explains how to install and use the reports app and what CDRs are used for

Preparation

If you don't have an AP running on the SSD of your IP411LEFT, please set up an Application Platform as described in the book.

So don't proceed if you don't have an AP running on your IP411LEFT.

In this topic we prepared a new start configuration for you. As a result, please load a new configuration onto your devices:

Upload new configuration to your Devices

This book also has a start configuration for your AP. So don't forget to click on the  Load initial lesson configuration to your Application Platform button once it appears. This may take a while, so bear with us and keep trying

To log into myApps use ckl and ip411 as password.

Use this address: https://hq-dvl-ckl2.training.innovaphone.com

Overview

The Reports app service consists of multiple apps. One of those apps is the Reports app.

 reporting system overview

Reports

The Reports app is used to collect call records that have been made in the system and then display those records to administrators. This allows for analysis of successfully answered, lost, or rejected calls, as well as information on which agent answered the call and how long the call lasted.

Call list

Every user can see his own calls or missed calls. A user can also see from whom the call came from or was diverted by.

Call list api

The API provides services for other apps to display personal call information. The phone or softphone app uses this API to display the call history directly in their apps.

Installing the Reports app

The initial download of the app service and the creation of the app service instance was already done, so you don't have to care for it. As a next step we will add 3 app objects for all apps integrated in the reports app service.

In order to do these please do the following steps

• Please open the Settings plugin
• Open the  reporting Settings plugin
• Click on  + Add app
• Select  Reports app
• You just have to press OK  as the names are already configured

While we are at it, repeat the steps for the  Call List app and the  Call List API.

Distribute the Reports app via the Config Admin template. Distribute the Call List and Call List API app via Config User template.

---

For historical reasons, there is some confusion regarding the name of the App. It should have been called Reports from the very beginning but it started out as Reporting and therefore, you find both names. The Settings plugin still creates the app with the SIPid reporting, so we roll with it.

The PBX configuration

To view call records in your Reports app, you need to collect CDRs (Call Detail Records) from the PBX. A CDR contains detailed call information for each call that passes through the PBX. The PBX must be able to generate CDRs, and then each CDR must be sent to the Reports app service via either an HTTP GET or POST request.

In the first step we have to enable the Generate CDRs check mark in PBX/Config/General. So go to PBX / Config / General and  enable the Generate CDRs option. If this option is unchecked, no CDR is created, so you will never see any call information in your Call List or Reports app.

Btw, for historical reasons, the Gateway level is also able to send CDR data, albeit with different format. However, we don't care as this is not used anymore.

As a next step we need to take care of sending the CDR to the Reports app service. Therefore we have to configure a CDR interface located on Gateway/CDR0 Gateway / CDR0

Please configure the following options:

• select HTTPS as Log Server Type
• use apps-dvl-ckl2.training.innovaphone.com as Address as this is the DNS name of your AP
  
• leave Port empty (which will use the https default port 443)
• select External (POST) as Method (External GET< is also possible)
• use /dvl-ckl2.net/reporting/cdr as Path
  
• use an appropriate User of your choice for CDR delivery. Note that this user name will only be used to authenticate the delivery of CDRs to the Reports App service instance. Here in the training, please use cdr (so that your teacher knows it and can help if need be)
• use an appropriate secure Password of your choice for CDR delivery. Note that this password will again only be used to authenticate the delivery of CDRs to the Reports App service instance. Here in the training, please use ip411 (so that your teacher knows it and can help if need be)

We now have  configured the client side of the CDR delivery on the master PBX.

An interesting case is the construction of the Path value. It probably was no surprise to you that it starts with the PBX's domain name followed by the string /reporting(/dvl-ckl2.net/reporting). However, the trailing /cdr is not intuitive. It is a fixed value and the destination to which a CDR must always be sent.

The app service configuration

Of course if we configure credentials on the sender side, we have to configure the same credentials for the authentication on the receiving side, otherwise the CDRs will be rejected.

To set the credentials, we have to open the reporting Settings plugin and open the Configuration dialog.

• set User name and Password  in the Account for the CDR authorization dialog to the values you have configured on the PBX side before (cdr and ip411)
• Do not forget to press OK.

CDR deletion

While we are configuring the reporting PBX Manager plugin, let's have a look at an important topic. By default, the Reports App deletes CDRs after 90 days. If you want to keep the CDRs indefinitely or change the duration of keeping the CDRs, you can disable this mechanism or  change the configuration to your liking.

By the way, believe me, you don't want to set it to disabled. CDRs will quickly fill your database and one day, your AP's disk will be full and it will not boot any more and  you're in trouble.

Trying it out

Let's see if the configuration is working or not.

Call yourself (extension 10) from the John Doe user. Then open the Reports app and click Show Results. Not a single call will be displayed. On the other hand, the call will appear in the Call List app and in the History section of the Phone app.

There's obviously something missing in our configuration, so let's move on to the next chapter to find out what it is.

Licensing

Call reports (as opposed to just listing your own calls in the Call List app) are only available to users who have been assigned a reporting license. Assigning the Reports App to users doesn't do the trick as it controls access to the Reports app. To have calls included in the reports, the users initiating or receiving the calls must have a Reporting license assigned.

So

•  assign the Reporting license to Config User
• call 10 again from John Doe
  
• refresh the list of calls by clicking on Show results again
• a list of calls will be displayed

When the Reporting license is assigned to a user, all subsequent calls will be listed in the Reports App. Previous calls will still not show up.

Set up a report

Now that we finally see some entries,  we can take a look at the left section (Set up report) of the Reports app. This section allows you to create a quick filter to display in your Report app.

To test the filter function,  please make some test calls. These test calls should not only come from John Doe, but also from the other phones, otherwise the filtering doesn't make much sense. Make sure you recorded a call from Jane Doe to yourself as well as a call from John Doe to Jane Doe.

• Anonymous: You can enable the Anonymous option to hide the real names and numbers of the calling and called parties.

• Name or SIP: If you either enter john.doe (SIPid) or John Doe only calls from the perspective of the user John Doe will be displayed.

• From -> To: You can specify a start and end date so that only entries in that time frame are displayed.

• AND Filter: You can add predefined filters to narrow the search results. Note that only entries that match the attached filter and the above settings will be displayed. If you add multiple filters, they will be combined with OR. This means that the result will be displayed if one of them is true. If this was confusing, we will give you a practical example in the next chapter.

Clicking the Show Results button will apply the current filter options and display a summary of all incoming and outgoing call statistics.  You can download the report as CSV, XML or PDF file.

Please test it and enter john.doe or John Doe in the Name or SIP field and then click Show results. Only calls from John Doe's perspective will be shown, all other calls (e.g. calls from Jane Doe) will be hidden.

External applications

If you have your own application, you can retrieve the PDF, XML or CSV file with an HTTP GET request. For this to work  you need to configure a user name and password as an external application account in the Reports PBX Manager plugin.

The path and syntax of this HTTP request are explained  in our Wiki.

How to create a filter

There are two ways to create a filter. You can either  click on the pencil icon or open the  Filter Settings in the burger menu of the Reports app. In both cases,  a new window will appear that allows you to define a filter.

Most of the settings are pretty self-explanatory, so we won't go into detail on each one but if you want to know more about each setting, please have a look  in our wiki

• Load filter definition for: You can either create a new filter or select an existing filter to edit.

• Base filter: You can select an existing filter to combine it with the one you are currently creating. It's important to understand that an AND logical operator is used to combine them.

This will make sense once we do something practical, so let's get started.

 Create a filter so that only calls from the remote party ckl are shown. Name that filter myself remote and  apply it as AND filter. This will result in a list of calls from the perspective of different users (Jane Doe, Johne Doe, ...) where you are the remote party of the call.

Please use copy and paste to create the filter name. Case sensitivity is checked by the configuration checker.

Our next goal is to filter only calls from the perspective of John Doe with the remote party of ckl.  So please create a new filter named john doe only for the local number 14.  Then add this filter to the list of filters on the left and click Show Results.

You may be surprised by the outcome as the list of calls grows. The reason is that by adding multiple filters an OR operator is applied. So the result of both filters will be displayed.

This means the goal of our last task was not been reached. As a result remove both filters by clicking the x button and go back to the Filter settings.

Edit the filter john doe only and use the filtermyself remote as the base filter. This will combine the filter with an AND operator will be used. The result is a list of calls from the perspective of John Doe with you as the remote party.

E-Mail settings

The Reports app can send scheduled (daily, weekly or monthly) emails with the report as an attachment. Filters can be applied to customize the report.

SMTP configuration

Before we can create scheduled reports, we first have to create a connection to an SMTP server. This is done in the reporting Settings plugin.

 Please configure the following options.

• Host name: Enter the Host name of the sender.
• Configure apps-dvl-ckl2.training.innovaphone.com
• Server: Enter the address of your mail server
• Configure training-mail.innovaphone.com:587
• User name: You need to authenticate at the mail server
• Configure dvl-ckl2@class.local
• Password: You need to authenticate at the mail server
• Configure ckl-pw
• Sender address: Enter the e-mail address that you want to appear as the sender
• Configurereports@class.local
• Sender name: Enter the name that you want to appear as the sender
• Configure Reports

If you are not satisfied with the default text, you can customize the text for the mail subject and body. If you want, you can use HTML in the mail body.

E-mail Report settings

Now that we have established a connection to the mail server, we can set up a scheduled report email. Therefore we go back to the Reports app and open the Burger menu and then E-Mail Report Settings.

This will open a new window that let us  set up this mail job.

Configure the following options

• Name: daily report mail
• E-mail addresse(s): dvl-ckl2@class.local
• AND Filter: john doe only
• Output Format: PDF
• Anonymous: unticked
• Send time: Set a time in the near distance future
• Time zone: Set your own Time Zone
• Interval: daily

Afterwards press Save.

To see if you successfully receive the reports as mail, log into our mail server:

 https://training-mail.innovaphone.com/owa/

username: dvl-ckl2@class.local

password: ckl-pw