Chapter 25. Reporting

Table of Contents

KonaKart Reporting from the Admin App
Modifying the Reports
Adding New Reports
Defining a Chart to appear on the Status Page of the Admin App
Reports Configuration
Defining the Set of Reports Shown in the Admin App
Accessing the Database in the Reports
Customer Events
Creating Customer Events

This section describes the KonaKart reporting sub-system. KonaKart uses the popular open source BIRT (http://www.eclipse.org/birt/) reporting system but it is loosely-coupled so it is easy to integrate an alternative or additional reporting system if you wish.

The mechanism of Customer events is also explained, and how they can be used to persist important information. This information can be used to generate reports to help you understand how customers are using the KonaKart store and so help you make modifications to improve the overall store performance in terms of usability and sales.

KonaKart Reporting from the Admin App

The reports are accessible from the "Reports" tab of the KonaKart Admin Application. A new browser window will be created that will run the BIRT viewer for the selected report.

Modifying the Reports

You will find the report files under the birtviewer webapp at: {konakart home}/webapps/birtviewer/reports/stores/store1 By default the reports have the .rptdesign file extension although this can be set in the configuration parameters to some other file extension if you wish. For very simple modifications to the reports you can simply edit the report files (they are XML files). You can edit them directly from the Admin Application or using a file editor of your choice. For more complicated modifications or for adding your own new reports, you will have to set up the BIRT/Eclipse report design tools as explained below.

(Note that from version 3.2.0.0 the default reports location has moved to accommodate Multi-Store functionality where each store has its own set of reports. This is why the new location has the store number at the end of the directory path).

(Note that prior to version 2.2.7.0 the "birtviewer" webapp was called "birt-viewer". The change was made due to certain application servers not being able to handle the name "birt-viewer" in all circumstances).

Adding New Reports

KonaKart has been designed to allow the integration of any reporting system. although BIRT has been used in the download package and makes an excellent choice for adding addition reporting functionality.

BIRT is a free Eclipse-based open source reporting system for web applications, especially those based on Java and J2EE. BIRT has two main components: a report designer based on Eclipse, and a runtime component that you can add to your app server. BIRT also offers a charting engine that lets you add charts. Included in the KonaKart download package we provide the "BIRT Viewer" web application that includes the BIRT runtime system which is all you need to produce your reports.

For development of addition reports you are advised to follow the instructions on the BIRT web site for setting up BIRT in Eclipse. Note that currently we are using BIRT 4.3.0 so it is strongly advised that you use that version for new reports to ensure compatibility.

Once you have created your new report you can either upload it using the Admin Application or simply add your report to the directory defined to hold your reports (the directory is a configuration parameter that is set up default to C:/KonaKart/webapps/birtviewer/reports/stores/store1 (therefore, this will have to be changed if you have not installed KonaKart in the default location on Windows. You can set this value in the Admin Application under the Reports Configuration section.)

To make your report appear in the list of reports with a friendly name rather than its filename you have to specify the text to display in the text-property title tag of your BIRT report, for example:


<text-property name="title">
        Orders in last 30 Days (Chart Only)
</text-property>

Defining a Chart to appear on the Status Page of the Admin App

By default KonaKart is configured to display a plot showing number of orders over the preceding 30 days on the Status page of the Admin Application. What you display in this particular frame is entirely up to you - you can choose another plot, or indeed any page you like that might even be unrelated to KonaKart. You define the URL for the page in the Reports Configuration section of the Admin Application.

Reports Configuration

By default KonaKart is configured to use port 8780. If you change this port you will have to modify the "Report Viewer URL" and the "Status Page Report URL" configuration parameters in the Reports Configuration section of the Admin Application to reflect the different port. These are set automatically if you installed using the installer so you should only need to do this if you either installed manually using the zip package or changed the KonaKart port number after installation. Here's an example of what you would set these parameters to if you were running KonaKart on port 8080:

KonaKart Reports Configuration

KonaKart - Reports Configuration

Defining the Set of Reports Shown in the Admin App

By default KonaKart is configured to search for report files with the .rptdesign extension in the C:/KonaKart/webapps/birtviewer/reports/stores/store1 directory. If you use a different file extension for your reports or you have installed KonaKart in any location other than C:/KonaKart/ you will have to modify the configuration parameter to suit your installation. You will have to modify the reporting configuration parameters in the Administration Application. You define all of the reporting configuration parameters in the Reports Configuration section of the Admin Application.

Accessing the Database in the Reports

KonaKart may be looking for the database connection parameters in the wrong file. Check your konakart.rptlibrary file under webapps/birtviewer/reports/lib/ . Find the beforeOpen section under <data-sources>:


<data-sources>
   <oda-data-source 
        extensionID="org.eclipse.birt.report.data.oda.jdbc" 
        name       ="KonaKart-Database" 
        id         ="4">
       <method name="beforeOpen"><![CDATA[

importPackage(Packages.java.util.logging);
importPackage(Packages.com.konakart.reports);

var dbPropsFile = 
    "C:/KonaKart/webapps/konakartadmin/WEB-INF/classes/konakartadmin.properties";
var dbparams = new GetDbParams(dbPropsFile);

this.setExtensionProperty("odaDriverClass", dbparams.getDbDriver());
this.setExtensionProperty("odaURL", dbparams.getDbUrl());
this.setExtensionProperty("odaUser", dbparams.getDbUser());
this.setExtensionProperty("odaPassword", dbparams.getDbPassword());

This is how the reports find out how to connect to the database. The konakart.rptlibrary file defines the location of the konakartadmin.properties file (or it could be your own file so long as it defines the appropriate database connection parameters). Therefore you must verify that the filename is correct for your environment. The default location is as illustrated above which shows the default location when installed on Windows. (This should be set automatically by the installation wizard but could well be set incorrectly if you used the manual zip-based installation).