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.