Custom Reports

Overview
Urchin's internal data processing and reporting engine is very powerful and can be configured to process virtually any type of data. This document has been created as an overview and guide for creating custom reports.

As shown in the figure below, there are two separate processes within Urchin that control the creation of reports. There is the Log Processing step which parses the raw log file data and populates a number report data tables. Log processing is triggered by the Urchin Scheduler or when you click the 'Run Now' button in the Administration.

The second process is triggered when someone actually clicks to view a report. All reports are created dynamically. Clicking on a particular report creates a query to the data tables which are compiled by the Reporting Engine and delivered to the user as a viewable report.

The key to creating valuable custom reports is understanding the three controls that affect reporting. The first control is the Log Format, which tells the Urchin Engine what is in the log file and how to process it. To create custom log formats, please see the appropriate article in this section of the manual.

The second control is the Data Map. The Data Map controls which fields are stored in which data tables. To create a custom report, you may need to create an additional entry in the Data Map as discussed below. The Data Map is critical to defining what information is available for reporting.

The last control is the Report Set. The Report Set contains the listing of reports that is seen in the navigation when viewing reports. The Report Set entries also contain the information necessary for making the query to one of the data tables, including the table number, and how to display the data. Creating a report set entry is discussed below.

Step 1: Select your Fields
You may need to reference the Regular Field List and Regular Report List in the Reference section of this guide to see exactly which fields are available and what existing reports are storing. Urchin data tables can correlate two fields together as an option. In general, the data tables store text data versus numeric data versus time. You will need to define the text fields and the numeric fields to use. See the examples at the end of this document.

Step 2: Create a new Profile Type
In the Urchin installation folder, copy one of the existing Profile Types in 'lib/reporting/profiletypes/' to 'lib/custom/profiletypes/'. Simply create a copy of the entire folder, such as 'Standard_Website', and place the copy into the 'lib/custom/profiletypes/' folder. The copy should include all of the files contained in the original folder. Be sure to rename the folder to give it a unique Profile Type name. Use underscores in the name instead of spaces.

Step 3: Edit the Data Map
In your newly created folder, there will be a "datamap.dm" file which contains all of the Data Table entries. The format of the file is described in the beginning of the file itself. Edit the file and create a new entry at the end of the file. Here are some notes on setting each field in the new entry:

  • TABLE: Make sure this is a unique entry between 1-200. This is the table id number that will be referenced during the query.
  • AFIELD: Use the Regular Field List in the reference section to look up the id value of the field you wish to report on.
  • BFIELD: If you are correlating two fields, enter the second field here and set the SEP field to a pipe symbol (|), otherwise leave these two fields as dashes (-).
  • IFIELD: Use the Integer Field List in the reference section to look up the id value of the field you wish to report versus.
  • REQUIRED: Set this to A, B, or BOTH to require the field(s) to exist before making an entry.

Step 4: Edit the Report Set
In the same folder, edit one of the Report Sets, (.rs files), to include the reference to your new table. You can also create a new Report Set if desired. This file contains entries in the same order as the navigation for the reporting. Each section of reports begins with a menu. Determine which section you wish to place your new report and copy one of the existing reports entries that matches the format and type of report you are creating. Edit your newly created entry as follows:

  • VID: The first field is the unique View ID. Modify this so that it is a unique value for this report.
  • NAVNAME/FNAME/NAME: Set all three of these fields to the name of your report. Replace the dictionary entry with the name in quotes.
  • IFIELD: Set this to one of (VISITORS,SESSIONS,PAGEVIEWS,HITS,BYTES,TIME,REVENUE,TRANS,ITEMS)
  • INAME: Set this to the text name of the Integer field.
  • TABLE: Set this to the table number created in the previous step.
  • HELP: Set to "-" for now.
  • FPART: If you used only Field A in the previous step, the set this to CFIELD1, otherwise you can grab BOTH.
  • FILTYPE/FILTER/FILCON/SOPT: Set all of these to "-".

Step 5: Configure and Process
Create or edit a Profile and set the Profie Type to the newly created Profile Type and the Report Set to the one created/edited in the previous step. Process log data and view your new report.