Linking Directly to Urchin Reports

Overview

In a standard Urchin installation, delivery of Urchin reports is controlled via the embedded session controller and Apache webserver that ship with Urchin. Users view their Urchin reports by authenticating themselves via an Urchin-controlled login process, and are then presented with a list of Urchin reports that they are authorized to view.

It is possible, however, to bypass Urchin's authentication and session controller and provide users with Urchin reports via a direct link from a portal or other external web site. Urchin 5 provides this capability as one of its standard integration points.

• If all Urchin report data is in /data/reports, read Basic Scenario, below.
• If Urchin report data is in a location other than /data/reports, read Advanced Scenario, below.
• If you are supporting multiple users with multiple profiles, and each user has his/her reports in his/her own directory, read Large Configuration Scenario, below.

Basic Scenario

This section applies to a standard Urchin installation, where all Urchin reporting data is located in the data/reports directory of the Urchin distribution and the Apache webserver supplied with Urchin (urchinwebd) delivers the content for the Urchin reports.

Step 1: Enable "Direct Report Linking"

• Log in to the Urchin administrative interface as the "admin" user.
• Navigate to the Settings -> Access Settings screen.
• Set the "Direct Report Linking" field to "on".

Alternatively, you can enable direct report linking by using the "uconf-driver" utility in the "util" directory of the Urchin distribution:

• Start a command shell on the Urchin system
• Change directory to the "util" directory of the Urchin distribution
• Set the direct report linking by typing:
  uconf-driver action=set_parameter recnum=1 cr_directlink=on
  

Step 2: Configure links to Urchin reports

For each profile (report) to which you want to provide a link, create a link in the following format:

  (baseurl)/report.cgi?profile=(profilename)&user=(username)

where (baseurl) is everything before session.cgi in the current URL, (profilename) is the URI-escaped name of the profile, and (username) is a user that has access to the report. The user= setting is optional and controls the language and localization preferences; if not specified, the admin user is assumed. For example,

  http://www.hollywoodweb.com/report.cgi?profile=www.hollywoodweb.com&user=johng

Advanced Scenario

Step 1: Enable "Direct Report Linking"

Follow Step 1 in Basic Scenario, above.

Step 2: Set urchin.cgi permissions

Make sure that bin/urchin.cgi and util/uconf-driver in your Urchin installation are accessible and executable by your web server user.

Step 3: Copy htdocs/report.cgi to the directory(ies) from which you wish to run it.

Step 4: Link/alias uicons, ujs, usvg, and ucss folders

The reporting interface needs access to certain javascript files and icons. From the directory that will contain report.cgi, create links or aliases to these folders. This can be done as symbolic links, web server aliases, or you can simply copy the folders into the location. To set up symbolic links:

	cd [report.cgi location]
	ln -s [urchin path]/htdocs/uicons uicons
	ln -s [urchin path]/htdocs/ujs ujs
	ln -s [urchin path]/htdocs/usvg usvg
	ln -s [urchin path]/htdocs/ucss ucss

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

Step 5: Ensure that the web server is configured to execute CGI applications.

For Apache, enable ExecCGI. Do not use script aliases.

Step 6: Edit htdocs/.report.conf

Uncomment the "Profile =" and "User =" lines if they are commented, and specify the profile and user. For example:

   Profile = www.hollywoodweb.com
   User = johng

Large Configuration Scenario

This scenario allows you to easily support multiple users with multiple profiles. Instead of creating a .report.conf file for each user-profile combination, you create a single .report.conf file that allows the report engine to dynamically extract the user and profile name from the URI stem.

The steps to establishing the Large Configuration Scenario are identical to the Advanced Scenario, above, except that instead of explicitly setting Profile and User in a .report.conf file, you specify a Regular Expression (as is commonly used in Tcl, Perl, C#, VB.NET, and other languages) in the URIMatch field. For example, if the user johng types in the following URL to get his reports:

   http://mach1.net/johng/www.hollywoodweb.com/report.cgi

then specifying the following fields in the .report.conf file would extract "johng" as the user and "www.hollywoodweb.com" as the profile:

   URIMatch = ^/(.*)/(.*)/report.cgi
   Profile = $2
   User = $1

Explanation: The URI stem is "/johng/www.hollywoodweb.com/report.cgi". The URIMatch field is a Regular Expression which parses out the user and profile from the URI stem.

• The first part of the URIMatch field is "^/" indicating that the URI stem must begin with a "/".
• The last part of the URIMatch field is "report.cgi" indicating that the URI stem must contain "report.cgi" before or at the end.
• The "(.*)/" means "extract the string up to the next "/" and save it (argument 1). Thus, the string "johng" is assigned to $1.
• The next "(.*)/" means "extract the string up to the next "/" and save it (argument 2).
• "Profile = $2" means assign the contents of argument 2 to Profile.
• "User = $1" means assign the contents of argument 1 to User.

Therefore, the steps for the Large Configuration Scenario are:

• Step 1 - 5: Follow steps 1 through 5 in the Advanced Scenario.
• Step 6: Create a .report.conf file that uses Regular Expressions to dynamically extract the user and profile name from the URL string that the user types in.