Using Domino Counter
Download Latest Version
Index

Welcome

Thank you for downloading the Domino Counter database. I hope this will prove to be a useful tool for your web site and Notes databases, and that it may prompt you to design your own innovative Domino agents.

This database is based on the principle that anything other web servers can do, Domino servers can not only do, but do better. The main reason why they can do better is that all the benefits of the Notes heritage can be utilized - multiple categorized views, replicated databases, Notes client and web client access etc.

You can achieve, using standard Perl or other cgi-bin tools, superficially identical results to Domino Counter. However, putting a graphical counter on a page, which these tools do easily, is only a small part of why you as a webmaster wish to use counter technology. Of far more use are the statistics generated behind the scenes - which pages are popular, when is usage heaviest, what is the international spread of usage, what type of browsers are most common - vital to active and progressive webmastering. The simple Perl routines fail at this sort of analytical use. Web counters also fail to address access by Notes clients - Domino Counter allows you to use a single counter to access from either client.

Unlike some other counter tools creating GIF images, Domino Counter does so in a way which avoids using the LZW compression algorithm patented by UniSys. Since UniSys have recently begun to threaten webmasters using non-licensed tools with legal action, the LZW-free status of Domino Counter is important to protect you and your company from such action, whilst remaining free.

Domino Counter is given free to the Notes community. If you like it and appreciate it, a small acknowledgement and/or link back to Rhizomatics is appreciated, but not demanded. Ideas for improvements are welcomed, as are even bug reports and complaints.
General Setup

Setting Paths for a New Counter database

The most crucial step in setting up the database is to get the database paths correct. Domino Counter relies on the double-sided nature of the Domino server - as a web front-end for Notes databases, and as a regular web server of plain, e.g. HTML and GIF, files.
Short Lesson on Domino Paths
Domino serves two types of content - rendered Notes documents from databases (NSF files) stored in the server's Notes Data directory (e.g. c:\notes\data), and native file system files from a directory structure which usually sits beneath the Notes Data directory. In this second mode, it operates in the same fashion as any vanilla HTTP server, simply serving up GIF, JPEG and HTML files, but including abilities such as Server Side Includes.

The Domino server installation program creates the domino directory structure automatically, with standard sub-directories domino\html, domino\icons, domino\adm-bin, domino\cgi-bin and domino\cache. Web files are stored within the domino\html directory, which may itself have a whole struture of subdirectories beneath it.

For example, on an NT server if the server Notes Data directory is d:\notes\data, the web file directory would be d:\notes\data\domino\html. Other operating systems follow a similar pattern, e.g. /opt/lotus/domino/data/domino/html.

Caveat: it is possible to override these default locations for the domino subdirectories in the Server document of the Name and Address book (a.k.a. in R5 as the Domino Directory database).

Key Point: As far as a client browser is concerned, domino/html is the root directory of the web server.

Hence, if your Domino server is called www.mycorp.com and the HTML directory is d:\notes\data\domino\html, the native file d:\notes\data\domino\html\web\index.html will appear to the web browser as http://www.mycorp.com/web/index.html. Note too that web directory will always be in forward slashes, but the file system directory will depend on your server operating system (backslashes for NT, forward slashes for Unix).

Domino Counter knows automatically the path of the Notes database, but needs you to tell it the Domino HTML directory paths - both from the operating system perspective (in order to generate dynamic GIFs and manage its cache) and from the remote web browser perspective (in order to generate a dynamic URL to pass to the browser).

It will create, by default, a counter directory underneath the domino\html directory, unless it has already been created by a system administrator - hence, the Domino server account must have the rights to create or delete files and make subdirectories in this area. You should place the DomCount.nsf database itself in the Notes data directory, or in a sub-directory of it.

Sample values:

Directory (o/s perspective) d:\lotus\domino\data\domino\html\counter
Directory (web perspective) /counter/
Database location d:\lotus\domino\domcount.nsf

Important News for Upgraders
Updating an Existing Domino Counter database


1) Refresh Design of your existing database

The database has been specified as a template called DominoCounter, so it's an easy matter to replace the design from a Notes client.

2) Copy non-design elements from the new template.

The database also contains non-design elements, such as documents for digit styles, error images and reports which are not copied by a Notes replace or refresh design.

An agent is incorporated (operated from the Refresh Contents button in the Admin Menu navigator) which will copy in all the required documents from a given database.These will overwrite any existing documents with the same key, but will not remove any other documents which you've added. The same Admin Menu also has a button to access the standard database Design Refresh in Notes.

Alternatively, manually copy in your existing Counter documents (and OLAP stats if you use them) from your existing DominoCounter database and make the new unzipped database the live one.

3) Upgrade existing Counter Documents

To ensure that your existing Counter documents are compatible with the new version, run the Upgrade\Counter Documents agent once from your Notes client.

4) Resave the Database Settings document

Use the preferences button on the navigator or the Edit Settings agent from the Actions menu.

This step is necessary to set any new default values in the preferences document, but while doing so, it is worth reviewing again the options presented.

5) Perform any version specific upgrades

v1.X or v2.X -> v3.X (or greater)

The internal structure of digit styles has changed from v1/v2 to v3 of Domino Counter.

Any counter styles you have previously received as part of Domino Counter, or new styles created by yourself, will no longer operate on v3.

For the standard styles supplied with Domino Counter, simply copy over the revised Style documents, either using the manual method as outlined above, or the automated Refresh Contents agent.

For your own custom styles, the simplest method to rebuild the style is to launch the image using MS Internet Explorer, save it as a BMP image, remove the original attachment, attach the newly saved BMP file, and execute the Decode Image button.

v2 or v3.0.1 -> v3.0.2

OLAP Statistics have been fixed

Prior to v3.0.2 fact documents did not have the Hits figure updated correctly by the OLAP statistics module. This now works correctly in v3.0.2.

To correct your existing OLAP statistics results, run the Upgrade\Convert OLAP Stats agent from the Actions menu. This need only be done once.

v1.X, v2.x or v3.0 ->v3.1

The security model has been overhauled in v3.1

Please see the Security Model section below for details.

Also, although it is not necessary to decode again any of your custom styles from pre v3.1 databases, there will be a slight performance gain to be attained from so doing.
Putting a Counter on a Web Page

N.B. The counter may be placed on any HTML page on any server. The WebCounter agent must run on a Domino server, but the page being counted may be on Apache, IIS, Netscape etc.

Account Documents

Each hit counter has its own Counter document in the Notes database, a URL which relates to the page it is on, and an Account code. The Account code can be a short, meaningful code which is easier to work with than a long page URL. If you don't use an Account code, Domino Counter will use the page URL to work out which counter is to be updated.

Each Counter document holds the current hit rate, plus options - such as the style, width, transparency - statistics, categories and a Site Group to which the counter belongs (could be a web site title, area of a web site, or any other way you wish to manage multiple counters). However, there's no need to manually create this document for each counter, if you have Enforce Accounts switched off in the database settings. If Enforce Accounts is switched off, Domino Counter will automatically create an Account document whenever you put a new hit counter on a page.

HTML

The counter is placed in an image using the format:

<IMG SRC="<web address>">

(N.B. that the HTML standard allows a variety of extra parameters to be placed on this tag)

The basic syntax for the Domino Counter address is:-

http://your.webserver.com/DomCount.nsf/WebCounter?OpenAgent

(If you have placed DomCount.nsf in a subdirectory, adjust this URL accordingly).

A number of optional parameters can be specified on the end of the URL:-
&K Do not increment counter. Useful for displaying a list of current counter status, without updating the figures.
&S=A Set the style of the counter to A. You can have as many styles as you can find digit sets, and label them with any code you wish. Single characters are however more efficient.
Set Style to NULL to send a tiny 1x1 blank image when no counter is to be displayed, but statistics on the page still required.
&W=5 The minimum width of the counter. The width will be left filled with zeros to make up the length. Domino Counter will automatically override this if the counter overreaches this limit.
&T=2 Make the second colour in the counter image transparent.
&X=MyAccount Specify an account name for the counter rather than the referring page address. If "Enforce Accounts" has been switched on, these must be created before hand in the database; otherwise they will be initialized on the fly.
&U Record this hit also as a unique user visit.
&V Display the unique visit count to date, rather than the page hit count to date.
&Debug Turn debugging mode on - errors are reported in detail as text, rather than images.
The caching hit rate, and hence the efficiency of the counter and impact on server resources, is maximized by leaving out the style and width parameters. Domino Counter will automatically match a given required number with a prebuilt image of any style and/or digit width if these are not given.

Example URL

<IMG SRC="http://www.acme.com/DomCount.nsf/WebCounter?OpenAgent&S=M&W=3&X=HomePage">

N.B. If you have no parameters to pass, the URL can be simplified further by removing the ?OpenAgent Domino command. In this case, Domino Counter will use the counter associated with the page URL, or create a new counter if this URL has none already specified.

Restricted Agents

If you're adding agents to your own server, then you will very likely have arranged Unrestricted LotusScript security for the account of the agent signer. This is essential for agents which manipulate local (i.e. Unix or NT) file systems, or which work on other databases. However, if you're databases are being hosted by an ISP, or you are not webmaster of your own site, then you may well have no more than Restricted LotusScript security. If you do, Domino Counter is still available to you, with limitations.

One restriction common to both of the supplied Restricted agents is that OLAP statistics cannot be maintained in a separate database - these agents can still maintain the detailed stats, but only in the same database as the agents are present. If you have specified a separate database in the Preferences document, this will be ignored.

WebCounterRestrict

Since building and cacheing dynamic GIF images is heavily dependent on the local file system, the usual graphic counters are not available under Restricted security. You can, however, continue to count page hits - as many webmasters actually prefer - by placing a single pixel blank image on the screen in a <IMG> tag. The example below shows the minimum URL format - this example doesn't use Account Codes and counts raw page addresses:
<IMG SRC="http://www.myserver.com/DomCount.nsf/WebCounterRestrict">
The WebCounterRestrict agent takes no Style, Width or Transparency parameters, but is in operation identical to a WebCounter agent with &S=NULL parameter. Even if you have Unrestricted LotusScript access, it is still worth using this agent (so long as the OLAP stats location restriction is not an issue) rather than the standard WebCounter agent - the Restricted version is smaller and faster, and - where no Account ID is required - can even be called without the ?OpenAgent URL command.

LinkCounterRestrict

This works identically to the LinkCounter agent - it's only restriction is the OLAP stats location one described above.

Counting Unique Page Visits

Traditionally, hit counters have recorded every time a page is requested, even if it is by the same user who has already visited the page 5 times in the same session. This makes it difficult to record unique visitors to the site, rather than simple page requests, and these inflated hit counts reduce the credibility of web statistics.

For anonymous users, there is no simple way to determine what is a new user, and when an existing user starts a new session (i.e. if the user logs back on again 8 hours later, this usually is counted as a new visitor, whereas if she visits 90 seconds later, it's the same visitor in the same session). The usual solution is to place a cookie on the user's browser, with a certain time-out value (which will equate to the length of a user's 'session' on your site).

Domino Counter, as of v3.2, can maintain separate page visits and page hit counts. These carry through not just the basic count, but also the daily/weekly/monthly stats, and the OLAP statistics. Additional parameters are available for the WebCounter, FastCounter and WebCounter restrict to control this. Since triggering of LinkCounter,LinkCounterRestrict and NotesCounter are all elective, these are always counted as visits and hits.

To indicate that a page hit is also a unique page visit, use the &U parameter
To display the visit count to date rather than the hit count, use the &V parameter

To automate the detection of each type of visit, use the following JavaScript in place of the simple <IMG SRC> call. Note the time-out seconds setting - this is a judgment call you must make for your own site: how many seconds before a user is regarded as staring a new session:
Sample in-line JavaScript for unique visit counting
<IMG NAME="Counter" ALIGN="Center">
<SCRIPT>

// Set number of seconds before user is assumed to have logged off
TimeOutSeconds=600;

// get current date/time
now=new Date();

// retrieve existing cookie, if exists
index=document.cookie.indexOf('DomCountLastVisit');

if (index==-1)

// no cookie present, therefore first visit to page

{
IncParam='';
}
else
{

// DomCountLastVisit cookie exists, get date/time value

countbegin=(document.cookie.indexOf("=",index)+1);
countend=document.cookie.indexOf(";", index);
if (countend == -1) countend = document.cookie.length;
LastVisit=new Date(document.cookie.substring(countbegin, countend));

// calculate seconds elapsed between last visit and now
// (N.B. if your page will only be used by recent browsers (IE4/5, NS4), you can
// use the Math.round function below for more precision)
// elapsed=Math.round((now-LastVisit)/1000); 

elapsed=(now-LastVisit)/1000;

if (elapsed<TimeOutSeconds)
// user still within same session
{
IncParam='';
}
else
// create agent parameter to indicate unique visit
IncParam='&U';
}
// set SRC for IMG tag (will auto-load as soon as this is set)
document.Counter.src="http://localhost/domcount.nsf/WebCounter?OpenAgent&S=V&X=CookieTest&V"+IncParam

// set LastVisit cookie value (after above tests and image loading)
document.cookie="DomCountLastVisit="+now;

</SCRIPT>
Adding a new Digit Style

Domino Counter requires a strip of numbers (and optionally time symbols such as AM,PM and ':') in BMP format to create a digit style. The numbers can be oriented lengthwise or widthwise, but must be uniformly spaced.

N.B. Domino Counter will not accept GIF images as new counter styles. There is no technical reason for this limitation, solely a legal one; loading GIF files requires use of the LZW algorithm, patented by Unisys, who make it practically impossible for freeware products to use the algorithm legally.

Once you have your number strip, adding a new style is a six step process:
That's it. Your style is ready to save and start using in Domino Counter.

The database comes supplied with a range of different styles. The largest collection on the Web of counter image strips can be found at DigitMania and more can be found at Counters,Counters, Counters from the URLs below.

http://www.digitmania.com/



N.B. Domino Counter accepts any images in uncompressed BMP format (from v2.2 colour support extends to 256 colours), with 32 being a reasonable maximum for compatibility and performance reasons. For images in other formats, such as JPEG or GIF, it is simple to save to BMP format using MS Internet Explorer.

Ununsual Styles & Proportional Spacing

Digit sets occur in several different formats. The simplest, and easiest to deal with, is the horizontal strip of 10 equally spaced digits. Occasionally you may come across a vertical strip, but Domino Counter will automatically adjust itself to decode these.

Other variants are styles with limited punctuation for times (colon, AM and PM), dates (dash), or both date and time. Domino Counter needs to be told which of these the types are and will automatically compensate when chopping up the digits. It will also mark the time enabled sets for the use of the DisplayTime web agent.

A more difficult type of digit strip is one where digits are not equally spaced - this can occur for digits intended to be proportionally spaced, sets where AM and PM take up more space than the digits, or simply as a result of poor design. As of v3.1, the Style screen now has an additional button - Digit Adjustment - which allows you to adjust the width of each digit in the set, and to set left and right margins. There are buttons on the box which pops up to re-decode the digits, to generate a set of preview digits, and to display the preview digits on screen. N.B. Some versions of the Notes client can be unstable after performing multiple GIF imports, so exercise care when working on this screen.


Gallery of Styles

For a catalogue of all the available styles loaded in your database, complete with links to the authors where known, use the CounterCatalog web agent supplied in the database, e.g.

http://www.myserve.com/domcount.nsf/CounterCatalog
Convert Any Number to an Image

An additional agent works just like the page counter, but renders any specified number into an image. It has the same &S, &W and &Debug parameters as WebCounter, and an additional parameter of &V to pass the number. N.B. Date/time digit sets can also have : (colon), - (dash), A (AM) and P (PM) passed as part of the 'number'.

e.g.

<IMG SRC="http://www.acme.com/DomCount.nsf/DisplayNumber?OpenAgent&S=G&W=6&V=230219">

results in the image



Displaying The Time

The time agent (DisplayTime) has a similar syntax to the number display. It will display the current time in 24 hour or 12 hour format (with appropriate AM/PM indicator) and in a style of your choice. For it to operate, you must have at least one clock or date/time style identified in the database, i.e. a digit set with a colon, AM and PM synbol. Clock time images are cached in the same way as counter images.

The default operation is 12 hour clock display. Use &M=24 for 24 hour clock
The only other optional parameter is &S. If omitted, the first clock style in the database will be used. The &debug parameter can be used for tracking errors or timing response.

Example:

http://www.myserver.com/DomCount.nsf/DisplayTime?OpenAgent&S=V

Counting Link Clicks and File Downloads

A specialized agent is introduced with v3.1 which can count events such as file downloads or clicks on links out of the page. This agent produces no graphic images, but can count the same page accounts as the other web or notes agents. Rather than being placed as the SRC parameter of an <IMG> tag, the LinkCounter agent is called from the HREF parameter of a <A> tag, with the actual hyperlink passed via the &L parameter to the agent.

If the counter account is omitted (i.e. no &X parameter is supplied), then a dynamic account will be created - unlike other counters this account will not be the URL of the page on which the counter sits, but the the link URL, so that you can monitor both the page being linked to and from which page it is being clicked from. If you supply an account name, the actual link URL will be stored in the SiteURL field on the Counter document.

If you wish to separately monitor downloads of the same file from different pages on your site, use unique account names to differentiate the LinkCounter locations. Since the target URL of the download file or link will still be recorded, you can analyze the statistics either by the target URL or the account name which specifies where the user was when clicking on the download icon. Alternatively, if you simply wish to monitor all downloaded files in total, rather than individual files, you could use the same account name (e.g. &X=Downloads) for every link.

Example (using an Account name):

<A HREF="http://www.acme.com/DomCount.nsf/LinkCounter?OpenAgent&X=Downloads&L=http://ftp.acme.com/pub/newfile.zip">Download newfile.zip</A>

Example (without Account reference):

<A HREF="http://www.acme.com/DomCount.nsf/LinkCounter?OpenAgent&L=http://http.acme.com/news.html">What's New!</A>

Performance Tip
If all your links to be counted will be on the same server, and you're using an R5 server, it's possible to improve the performance of LinkCounter by using the Internal Redirect option in the Settings document. Select Off to never use Internal Redirect, On to always use it and Auto to switch it on for relative addresses and off for absolute addresses.

Internal redirection - otherwise known as double-bracketed redirection - is a Domino trick to cut down on unneccesary web traffic. In a standard redirection, the client browser opens a URL to a page or agent on the Domino server, this page/agent then returns a (single-)bracketed URL back to the browser, which then sends that URL back to the server again, which then returns the page to which the redirection points.

This long-winded double journey is unavoidable if the URL being redirected to is on another server - however, if it's on the same server, it's a complete waste of time. Whenever Domino sees double-brackets around a URL, it immediately fetches the page being referred to, and sends that directly to the client browser, cutting out the intermediate round trip. Internal Redirection has been around since Domino 1.0/Notes 4.5 but is only reliable to use as of R5 - it cannot handle URLs not present on the same server, hence the Auto handling used here.
Putting a Counter on a Notes Page

The database contains a special agent which allows page counting to work with Notes clients too. Notes users don't get a graphical counter, just a plain bit of text, but their statistics can be amalgamated with web users. This type of page counting requires no change to database ACL - pages can be counted for users who have no more than Reader access to a database, unlike cruder formula and profile document based age count methods. The counting process works by making the Notes client execute the agent inside the Domino Counter database - this agent then performs all the required counter document updating.

For statistics gathering, in place of the web UserAgent, you get recorded the full Notes client version, and in place of the network address, you get the full hierarchical user name. Key to this joint Notes/Domino page counting is the use of simplified account names (sites) in place of URLs to identify each page. A Notes form intended for both types of clients can have appropriate formula to generate a IMG tag for web users, and a Notes computed text formula for Notes users, with hide-when formulae to keep the appearance right for each client. So long as both sets of formula refer to the page with the same account name, a single set of statistics will be kept for that page, counting web and Notes client access.

There are two methods of calling the NotesCounter agent.

@Environment( "PageCount")

Example LotusScript is shown below, (note the extra lines required for PostOpen calls) :

Sub Postopen(Source As Notesuidocument)
     Dim session As New NotesSession
     Dim DomCount As NotesDatabase
Dim CounterAgent As NotesAgent
     Set DomCount=New NotesDatabase("YourServerName","DomCount.nsf")

' static account
PageRef$="MyPageIdentifier"

'  Sample alternative dynamic account generation, from field AccountRef on form
'     PageRef$="Report: "+source.document.AccountRef(0))

Set CounterAgent=DomCount.GetAgent("NotesCounter")
If Not (CounterAgent Is Nothing) Then
         Call session.SetEnvironmentVar( "AccountRef",PageRef$)
         Call Counteragent.Run

' extra lines required for PostOpen event
    PageCount = session.GetEnvironmentString( "PageCount" )
   Call Source.FieldSetText("CounterFieldName",PageCount)

    End If
End Sub

The areas requiring local customization are italicized. Use the Page Reference to uniquely identify the page - this could be by a document ID (if the document has already been saved), form name, key value, or some combination thereof. For single document forms, such as profile documents or R5 pages, a static value, e.g. form name, is sufficient. Using common account references for web and notes counters, it is possible to maintain a single count of how often a page has been accessed, regardless of client.

N.B. All users accessing the page being counted must have edit access to the Domino Counter database, since this QueryOpen/PostOpen event runs the agent and passes enviroment values on the client PC, not the server. To restrict security, use form and view restrictions to prevent users accessing the database directly, and not by means of permitted agents.


Scheduled Agents

Two scheduled agents are supplied with Domino Counter:-

For efficient counter processing, and space conservation, use both of these agents. By default the Purge agent operates weekly, on a Sunday at 2am and the PreBuild agent operates every two hours. You may amend these schedules to fit your own environment.

The Prebuild agent can be tuned by setting the BuildAhead value for each counter. This determines how many images the Prebuild agent should prebuild for each counter. For example, if the HomePage counter had a current hit count of 312 and a BuildAhead of 10, the Prebuild agent would create in advance the images for 313,314,315,316,317,318,319,320,321 and 322. The next 10 times the home page is accessed, therefore, Domino Counter will have no need to build the image and can immediately deliver the prebuilt counter, resulting in faster response for the user, and reduced processing overhead for your server.
Querying, OLAP and Reporting

Notes views are supplied for basic counter monitoring, either by account/page reference or by category. These views show current hit counts, historical counts, counts per day, images built and cache hit rate.

Top 40 Pages

Additionally, a 'top ten' list of popular pages can be displayed using the hidden web view with an alias "PopularPages". This produces a HTML table of pages, with hyperlinks to the host page, a description of the page (where available, if not the account is displayed) and the current hit count. This view is available to all Anonymous users. The hotspots on each view entry are redirected to point to the page being counted, rather than the Counter document s might be expected in a Notes view.

Use the &Count= parameter of the Domino ?OpenView URL command to control how big your list is. An example URL is shown below:-

http://www.myserver.com/DomCount.nsf/PopularPages?OpenView&Count=10

Excel Web Queries


Web users can also use the web query and Excel pivot table. All code for the web query and pivot table view is available within this database for modification or re-use within your own systems. For more information check the series of articles on Excel/Notes integration in the late 98/early 99 back issues of DominoPower magazine.


To use the web query from within Excel, detach the file below to your MS Office query directory (usually c:\program files\microsoft office\queries). Following that, use the Run Web Query menu option (under Get External Data) in Excel to retrieve the statistics. (Alternatively, for Excel 2000, simply double-click on the IQY file and Excel will automatically perform the web query.)

The spreadsheet can then be enhanced (e.g. totals added, graphs inserted) and saved to disk; to update your customized spreadsheet in the future, right-click on the data and choose Refresh. N.B. the Excel query link requires a HTTP connection to the Domino server; no other middleware is required (no Oracle, no Notes drivers needed).



OLAP Stats

Domino Web Counter offers basic statistics gathering for each counter, including simple and detailed browser analysis. For more powerful reporting, it offers multi-dimensional (a.k.a. OLAP) statistics gathering for powerful reporting. These stats can be gathered in the same database as the counters, or in an optional separate database. If a separate database is used it must either be created with the same design template as the main counter database or have at least the hidden view (Stat Lookup) copied into it, and ideally the Stat form too.

Fact documents are created with two measures - number of hits and visits, and a choice of dimensions, including a choice of hierarchies for the time dimensions. Dimension selection is carried out from the Settings document. The more dimensions selected, the greater the processing time and disk space requirements to hold the data. On the other hand, each dimension is a different independent method of analyzing the resulting data, and can be used in combination with other dimensions for any type of query.
Measures: Hits, Visits
Dimensions: Counter, Domain, Browser (Simple), Browser (Detailed), Date/Time, Site Group
Date/Time Hierarchies: Weekend/Weekday, Day of Week, Quarter, Year/Month/Day,Year/Month,Year

Three simple views are provided to analyze the fact documents (by year/month/day, by browser and by domain). However, to benefit from the full available power, a separate reporting tool or hypercube builder, such as Seagate Info, Business Objects, Cognos, MS Access or Excel is recommended.

XML Reporting

Optional reporting by XML is now included with v3, both as a useful new way of reporting, and as an example of how to code the various XML delivery components in Notes, and in a dynamic fashion. N.B. This requires an XML-enabled browser, MS Internet Explorer 5 recommended.

The sample report included here has a number of features which distinguish it from vanilla XML or what can be done with HTML:


There are three elements required for an XML report, each with its own LotusScript agent (all source code included):

To display the report, call the web agent which produces the XML data. An example URL is:

http://www.me.com/domcount.nsf/report.xml

The plainly formatted data includes the following lines, which call the other two web agents to complete the output:

<?xml:stylesheet type="text/xsl" href="http://www.me.com/domcount.nsf/report.xsl"?>
<report xmlns="x-schema:http://www.me.com/domcount.nsf/report_schema.xml">

N.B. You must ensure that the Base URL is set in the database preferences, so that the correct URLs can be built for both the stylesheet and namespace. In the examples above, it is highlighted in green.

An XML enabled browser will show not the actual XML file (although this can be seen using the 'View Source' option), but the dynamically generated HTML produced by the actions of the stylesheet on the base data. Internet Explorer 5 will also allow you to call the stylesheet and namespace directly from the browser, and display these as properly structured documents, rather than plain text - a useful aid in debugging XML.

To expand the reporting capabilities, it is not neccesary to create another stylesheet, namespace and XML data output for every report - all that is required is a new stylesheet for the new report. A stylesheet can contain not only HTML formatting instructions, but also filtering, field selection and sorting power, and can as easily create a graph in SVG or VRML as construct an HTML page.
Other Agents

The SiteMap will produce a simple unnumbered list of links to each counter with a URL recorded. This is intended to make spidering of Domino sites by web indexers easier. The address to submit to the spider will be of the form:

http://www.myserv.com/DomCount.nsf/SiteMap

Security Model

The Domino security model for web agents, as described in the documentation, allows a simple choice for authentication between the signer of the agent and the remote browser user who runs the agent. In practice, operation is not so simple, since Domino cannot be relied upon to consistently apply the published security model - and the pattern of inconsistency varies between QMR and QMU releases.

The one certainty in a security model for a web agent such as a counter agent, is that there must be no authentication box for access to such an agent. It would be ridiculous to expect a casual visitor to a corporate home page to be faced with a login box before the page counter could appear in the browser.

The next principle, is the need to assign remote users the minimum possible permissions in order to execute the agent. In the context of the apparent Domino security model, this can fairly easily be accomplished using a combination of public access switches and the ability to base security for an agent on the signer. This will not, however, actually work - at least until Lotus iron out the problems with web agent security.

v3.1 applies the following security model:

N.B. For upgraders to v3.1, run the Upgrade\Make Documents Public Access agent once after upgrading in order to support the security model above. This will add a field called $PublicAccess with a value of "1" to each document - this permits web users with Reader access to update such documents via web agents.

If Anonymous rights are set to Editor, then there's no need to set individual documents to Public Access; however, it is not recommended for Interenet use to give unknown browser users a whet more access rights than is absolutely necessary - somebody, somewhere will try to abuse any such gap in your web armour.

FAQ


I can't get any counter to appear on my page / an error image appears

Check that:-

a) You have signed the Domino Counter database with a locally certified ID. This can be done quickly and simply using the Database Tools section of the Notes Server Administration screen.

b) Try executing the agent directly from the browser, rather than specifying the address inside an IMG tag. When you do this, any error messages returned by the Domino server or Domino Counter will be displayed on the screen, whereas when called by an image tag, the browser will only display a 'bad image' icon. You can obtain further textual information on any problem by using the &debug parameter.

e.g. http://myserver/DomCount.nsf/WebCounter?OpenAgent&debug

If you don't get a debug report, then the agent is not being run at all - either because your URL is not specified correctly, or there's a permission problem on the server.

c) Make sure that the correct paths have been set and that the web path and OS path agree. Domino Counter must be able to place its counters into a directory that is visible to web users. For Domino servers, this is in the domino\html directory usually beneath the notes\data directory. The default OS path value is c:\notes\data\domino\html\counter which matches to a default web path value of /counter/.

If you choose to change the name of the Domino Counter directory, or put it into a subdirectory of html, then change both web and os paths accordingly. If your domino\html directory is not on the c: drive then change the OS path to suit. N.B. Domino Counter v1.2 and above automatically create this directory if it does not already exist.

d) Check the syntax of your URL. If you've shifted the DomCount.nsf database to a subdirectory on the server, your URL will have to change to compensate. Easy way to test your root URL is to open the DomCount database directly in a browser. The simple URL http://myserver/DomCount.nsf will open up the default web navigator of Domino Counter, if your URL is right.

e) Make sure you have image styles in the database! Domino Counter comes with a preloaded selection, but if you've deleted all of these, it isn't going to be able to build any counters.

f) Check the type of processor in your server. Different processors handle binary data in different ways ("LittleEndian" or "BigEndian"). You don't have to know what that means, only that if you have an Intel or Dec Alpha based server, you're LittleEndian and if you have a SPARC you're BigEndian. The Settings document has a simple switch between these two binary orders.

g) Check the Server's Agent Restrictions. Since the agent must create files at operating system level, it is categorized as an Unrestricted LotusScript Agent. Ensure that the agent signer (if signer-security is being used) is included in the Agent Restriction section of the appropriate server document in the public Name and Address book (a.k.a. in R5 as the Domino Directory).

h) Check the Agent Execution Rights option. The rights to run a Domino web agent can be determined by who signed the agent, or by the person executing it (the choice is made via the "Run Agent as Web user" option on the agent's properties box). Since the latter will usually be anonymous, the agent signer method is preferred.
N.B. An excellent summary of the issues involved in Domino web agent execution and security is available in Julie Kadashevich's article in August 1997's Notes Today webzine.

i) Check the Database Access Control (ACL) There must be an entry for Anonymous, to prevent the server requesting authentication for every access. However, so long as the agent is being run with the signer's security (see item above) there is no need to give Anonymous users any more than No Access access, so long as the Read Public Documents is switched on. All of the web agents, and all of the error report forms, are marked as public documents.

j) If you upgraded, did you follow the upgrade procedure? Some Counter elements require upgrading between versions. If you've replaced or refreshed the design of an older Domino Counter database, you must at least (1) run the Upgrade\Counter Documents agent once, and (2) edit/re-save the database preferences. Failure to do so may cause the web agents to fail with illegal data, since data validation is stripped to the essentials for performance.

The explanation text for error messages doesn't appear in the &debug screen

This can be for two reasons: a) the error documents have not been copied from the supplied Domino Counter master database when the database was installed or updated, or b) the Error Reports view does not have Reader access for user Anonymous (it is not sufficient to enable Public Access User rights for the view)

How do I add my own styles?

How can I get transparent counter backgrounds?

Domino Counter will let you make any single colour in an image transparent. This can be controlled either in the counter document or by using the &T=x parameter, where x controls which colour is made transparent. Usually, the background is the first colour in the image colour table, so &T=1 will produce your desired transparent background. This may differ between images, so some experimentation may be required - however, in the process you may find some interesting effects making other colours disappear.

How can I find out who is visiting my pages?

The web counter agents maintain a LastBrowser and LastAddress field automatically in the Counter document to record. For Notes users, the full name is used in place of the Address, and the Browser identifier string built from the version number.

Alternatively, use Browser Analysis or OLAP statistics to build up a picture, at a summary level, or a detailed breakdown by Browser Identifier - the latter will differentiate between versions of Internet Explorer and operating system. There is a small penalty in performance however for analysis, although for summary analysis this is minimal.

How can I monitor a page without putting a counter image on it?

You can use a special style, NULL, to process a page for statistics but not build and present a graphic counter. You still require an <IMG> tag on the web page, in order for the agent to be called, but it will return a tiny (85 byte) single pixel transparent image that will be unnoticed on the page.

e.g. http://myserver/DomCount.nsf/WebCounter?OpenAgent&X=HomePage&S=NULL

Tip: If you don't require OLAP stats to be recorded in a separate database, consider using the WebCounterRestrict agent instead of the standard one - it always returns the NULL image, so there's no need to use the &S parameter, and it's also quicker to load and run.

How can I exempt certain network addresses from analysis?

The settings document can contain a list of network addresses, which will omitted from all statistics, i.e. access from these addresses will not increment page counters and not be included in browser analysis. This can be useful, expecially when testing, to prevent false counting.

The addresses you enter here can be complete network addresses or partial addresses. For example, you could enter 127.0.0.1 to exclude access from the server's own web browser from the statistics, or 196.23.45 to omit your entire intranet of 196.23.45.100, 196.23.45.101,196.23.45.101 etc. The format of the addresses depends on your Domino server's configuration - whether it refers to browsers by IP address or performs a remote DNS lookup to get the host name.

How do I prevent the counter incrementing when a page is hit several times in the same session?

Session based hit-counting, rather than counting every time an image is requested, can be accomplished using some JavaScript and a cookie on the target web page. See the Unique Visit Count section for details.

How can I show the page count on the Notes document being counted?

There are two ways of doing this:

Sample Source Page Update Scheduled Agent
REM "Use the AccountRef formula to mimic the way dynamic Account codes are generated on the source pages";
REM "N.B. This formula is just an example, creating a dynamic account from the prefix KB- plus the first and last words of the subject. Replace with your own dynamic account code formula";
AccountRef:="KB-"+@Left(Subject;" ")+"-"+@RightBack(Subject;" ");

REM "Optionally record the old values - this lets you add 'recent movers' marks to your top read document charts";

FIELD PageHitLast:=PageHits;

REM "Use the Replica ID of the DomCount.nsf database, rather than the Server/Database name for maximum compatibility";
REM "N.B. 80256679:006D5AA4 is just an example Replica ID - replace with your own";

FIELD PageHits:=@DbLookup("";"80256679:006D5AA4";"(Counter Lookup)";AccountRef;"Counter");
FIELD PageVisits:=@DbLookup("";"80256679:006D5AA4";"(Counter Lookup)";AccountRef;"Visits");

SELECT @All

Can I mail stats to my users?

There isn't an agent for this at present, but it is scheduled for a future Domino Counter release. Meantime, if you wish to run your own agent, either using the simple Notes agent actions or in code, there is a field called StatsRecipient in the Counter form for this purpose.

How can I stop people from accessing the &debug page?

You can switch off &debug access via a switch in the Security section of the Settings document.

What does it cost?

Nothing. Rhizomatics reserve the right to charge for any future enhanced version, but whatever, you may continue to use this current database for the rest of your Domino-using life. If you really feel appreciative, then a little acknowledgement on the counter with a link back to us would be sweet.


Isn't it inefficient to use LotusScript rather than say perl?

Using LotusScript has the big advantage of moving all the admin for managing counters and styles within Notes databases, with all their facilities for extension and security. What's the price for that extra functionality?

Domino Counter has efficiency advantages over standard cgi-bin scripts: it doesn't require an operating system shell to be created to load Perl and run the script (cgi-bin scripts can hit your server hard), and executes within the already loaded Notes agent manager. Also, Domino Counter has some clever structure that makes it more efficient - most perl counter scripts decode the image and encode it into a counter on every execution - Domino Counter decodes the image once (when you create a new counter style) and reuses cached used images or prebuilt images wherever possible.

So with Domino Counter, you have all the advantages of databased counter processing, without the performance price. The only way to squeeze better performance is by using Java servlets - watch this space!

If you do want to squeeze every last piece of performance out of DominoCounter, an alternative lean, mean agent called FastCount is added for v2. FastCount doesn't support Browser Analysis or the &debug parameter, and hence should only be used once you've already successfully made the standard WebCounter agent work. It operates identically in other respects, and maintains the same basic account information.

Updates

For updates to this counter, check:-

http://www.rhizomatics.co.uk/software/

If you liked Domino Web Counter, check out Domino Banner Ad, Domino Media Store, Domino Active Script Library and Server Side Cookie Jar available from the same site.

A discussion group, with hundreds of Rhizomatics users around the world, may be accessed at:

http://www.egroups.com/group/rhizomatics

Disclaimer

LIMITED WARRANTY


COPYRIGHT AND LICENSE


Acknowledgements
----------------

Domino is a registered trademark of Lotus, a subsidiary of IBM
GIF is a registered trademark of CompuServe and UniSys

Copyright (c) 1998-2000, Rhizomatics