Linking Directly to Reports From a Script or Portal

Overview
The Urchin 4 front-end is built on modular components and industry standard techniques to allow administrators to integrate report access into their existing or planned infrastructures. Many service providers will have a one-to-one relation between a customer and a website, and wish to link to reporting for a particular website directly from the websites administration area. Similarly, some providers will have a Portal for their customers to use, which links to various services and applications.

The example below illustrates how to link directly to a particular report, bypassing the administration, authentication, and session controlling components of the Urchin front-end. In order to use this type of configuration, it is assumed that the web server, user authentication and report access is governed outside the Urchin system. Urchin will still need to be configured for generating reports (Profiles), but this can be automated within or outside of the administrative interface.

Linking directly to a report is accomplished by using either a wrapper script or an existing Portal to call the urchin.cgi report engine located in the bin directory of the distribution. Parameters are passed to the report engine using a standard CGI GET method interface. This interface delivers the variables as name value pairs set in the environmental variable, QUERY_STRING. In particular the rid and lang variables can be used to specify the specific report to view and the display language. The rid can be determined using the uconf-driver utility as shown in the example below.

Using a simple wrapper script, the Urchin reporting can be called directly. And for a complex portal integration, the Urchin engine will propagate session and other portal variables in order to keep the session operating. The following example uses a wrapper script written in perl to access a report directly. While we cannot contemplate all possible configurations and Portals within this document, hints for generalizing this technique and using a Portal can be understood from the example.

Step 1: urchin.cgi permissions
The first step in linking directly to a report is to make sure the urchin.cgi binary located in the bin folder of the Urchin installation is accessible and executable by the user that your web server is running as. Also, the uconf-driver utility located in the util folder of the Urchin installation will need the same access.

Step 2: link/alias uicons and ujs folders
The reporting interface needs access to certain javascript files and icons. From the location where the wrapper script will live, create links or aliases to these folders. This can be done as symbolic links, web server aliases, or simply copy the folders into the location. Here is how the symbolic links are done:

cd [wrapper location]
ln s [urchin path]/htdocs/uicons uicons
ln s [urchin path]/htdocs/ujs ujs

When using symbolic links, be sure your web server is configured to allow the following of symbolic links. For Apache, this is the FollowSymLinks directive.

Step 3: copy script into location
Copy the script included at the end of this file into the wrapper location. The name of the file should be index.cgi or another name recognized by the web server as a CGI executable. Be sure that the webserver is configured to execute CGI applications. For Apache, this usually requires the ExecCGI directive, the .cgi handler to be turned on, and script aliases to be avoided.

Step 4: edit script parameters
Edit the first section of the script, lines 7-9, to set the location of the Urchin installation, the report that you wish to link to, and the language that should be used for display purposes. In particular, the reportname variable can be hard coded to a particular report or you could use another method for determining the reportname, such as the name of the directory that the script lives in. For example, if each user accesses this script within their administration area within their own website directory, and the name of the website directory is the same as the report name (Profile), then the script could capture that name from the path and use as the report name, using something like:

#---example path is of format /www/[report name]/urchin
$dir = `pwd`;
$dir =~ '/www /(.*)/urchin';
$reportname = $1;

Step 5: test run
Test the script from the command line first to make sure there are no errors. Then try viewing from a browser. Check user permissions and the error log of your web server if there are problems. If you still have trouble and are under a support agreement, contact our Engineering Services for help.

Wrapper script

#! /usr/bin/perl

#-------------------------------------------------------------
#  set path, report and language
#  (edit this part only)
#-------------------------------------------------------------
$urchinpath = "/usr/local/urchin4/";
$reportname = "www.urchin.com";   #---or grab from directory name?
$lang = "en";

#-------------------------------------------------------------
#  read configuration for reportid.
#-------------------------------------------------------------

$result = `$urchinpath/util/uconf-driver table=profile action=seek name=$reportname`;

$result =~ /recnum=(\d+)/;
$rid = $1;
if ($rid < 1) {
   print "Content-type: text/HTML\n\n report $reportname does not 
exist\n";
   exit;
}

#-------------------------------------------------------------
#  force rid and lang values in QUERY_STRING
#-------------------------------------------------------------
$ENV{QUERY_STRING} =~ s/(^|&)(rid|lang)=[^&]*//g;
$ENV{QUERY_STRING} .= "&rid=$rid&lang=$lang";
$ENV{QUERY_STRING} =~ s/&+/&/g;
$ENV{QUERY_STRING} =~ s/^&//;
$ENV{REQUEST_METHOD} = "GET";

#-------------------------------------------------------------
#  call urchin.cgi
#-------------------------------------------------------------
$result = `$urchinpath/bin/urchin.cgi`;
print $result;