Configuring the Statistics Handler

Introduction

This document describes how to configure the statistics handler in EPiServer CMO. CMS pages related to any active campaigns contain injection which makes user browsers send requests to the statistics handler.

The installation files needed to configure the statistics handler can be downloaded from EPiServer World. The statistics handler processes statistics data coming from users and saves raw visit logs to the statistics storage.

Statistics Data Handling

Each request contains parameters that cannot be detected on server side. The statistics handler tries to find and parse the following information in the request query string:

• CMS page ID (GUID)
• Original URL referrer
• User ID is a simple generated indentificator to track requests from the same user
• Event type indicates user action – open page, leave page, download file or post form. The handler also detects the user agent and user IP address. If data is related to pages from active campaigns, the handler saves raw log entry for each page’s campaigns.

Statistics Handler Deployment and Configuration

1. Create a new website to host the statistics handler. If you need, handler can be added to the existing website. Website application pool should use .NET Framework version 4.0 or higher.
2. CopyEPiServer.Cmo.Core.dll, EFExtensions.dll and log4net.all files to the /bin directory of website.
3. If the website does not already have aweb.config file, create one under the root of the site.
4. Configure database connection for data model using ADO.NET Entity Framework format. Add the following elements and update it with your specific connection parameters.
   

   <configuration>
      <connectionStrings>
          <add name="CmoEntities" 
               connectionString="metadata=res://*/Entities.CmoModel.csdl|res://*/Entities.CmoModel.ssdl|res://*/Entities.CmoModel.msl;provider=System.Data.SqlClient;provider 
               connection string=&quot;Data Source=.\sqlexpress;Initial Catalog=Cmo;Integrated 
               Security=True;MultipleActiveResultSets=True&quot;" 
               providerName="System.Data.EntityClient" />
      </connectionStrings>
   </configuration>

5. RegisterStatistics handler for IIS. See below.
6. You can also need to configure IIS to forward the request for *.stat file name extension to ASP.NET. For more information about how to configure a handler for a custom file name extension, see How to: Configure an HTTP Handler Extension in IIS (http://msdn.microsoft.com/en-us/library/bb515343.aspx). Make sure that IIS will not check if handler file physically exists on disk.
7. Verify configuration parameters defined on the CMO Settings page in the General Settings tab in EPiServer CMS Admin mode. The statistics handler uses cache timeout parameters.
8. If you need to have debug logs, you can define logging configuration. See details about log4net configuration at http://logging.apache.org/log4net/. Sample configuration withDebugOutput and file logging:
   

   <configuration>
      <configSections>
          <section name="log4net" 
                   type="log4net.Config.Log4NetConfigurationSectionHandler, log4net, 
                   Version=1.2.10.0, Culture=neutral, PublicKeyToken=1b44e1d426115821" />
      </configSections>
          <log4net>
             <appender name="OutputDebugStringAppender" 
                       type="log4net.Appender.OutputDebugStringAppender">
                <layout type="log4net.Layout.PatternLayout">
                   <conversionPattern value="%date [%thread] %-5level - %message%newline" />
                </layout>
             </appender>
             <appender name="RollingLogFileAppender" 
                       type="log4net.Appender.RollingFileAppender">
                           <file value="Statistics.log.txt" />
                           <appendToFile value="true" />
                           <rollingStyle value="Date" />
                           <datePattern value="yyyyMMdd " />
                <layout type="log4net.Layout.PatternLayout">
                   <conversionPattern value="%date [%thread] %-5level - %message%newline" />
                </layout>
             </appender>
                <root>
                   <level value="DEBUG" />
                   <appender-ref ref="OutputDebugStringAppender" />
                   <appender-ref ref="RollingLogFileAppender" />
                </root>
          </log4net>
   </configuration>

Registering Handler for IIS

See details about handlers registration at http://msdn.microsoft.com/en-us/library/46c5ddfy.aspx.

Register Handler for IIS 7 Running in Classic Mode

1. In the application'sweb.config file, create an httpHandlers section.
2. Create a handlers element in thesystem.webServer section.
3. Add the following elements to register the handler:
   

   <configuration>
      <system.web>
          <httpHandlers>
             <add verb="GET" path="{file_mask}" 
                  type="EPiServer.Cmo.Core.Statistics.StatisticsHandler, EPiServer.Cmo.Core" />
          </httpHandlers>
      </system.web>
      <system.webServer>
          <handlers>
             <add name="StatisticsHandler" verb="GET" path="{file_mask}" 
                  Modules="IsapiModule" scriptProcessor="FrameworkPath\aspnet_isapi.dll" 
                  resourceType="File" type="EPiServer.Cmo.Core.Statistics.StatisticsHandler, EPiServer.Cmo.Core" />
          </handlers>
      </system.webServer>
   </configuration>

4. Replace FrameworkPath with the correct path to the Aspnet_isapi.dll file.
5. Make sure to change the {file_mask} parameter to the correct mask of the web service that you configured during the installation of EPiServer CMO. For example, if your web service URL is “http://localhost/mywebservice.stat” you could specify “mywebservice.stat” or “*.stat” instead of this parameter.
6. Add the following elements to register the handler:

Register Handler for IIS 7 Running in Integrated Mode

1. In the application’s web.config file, create a handlers element in the system.webServer section.
   Add the following elements to register the handler:
   

   <configuration>
      <system.webServer>
          <handlers>
             <add name="StatisticsHandler" verb="GET" path="{file_mask}" 
                  type="EPiServer.Cmo.Core.Statistics.StatisticsHandler, EPiServer.Cmo.Core" />
          </handlers>
      </system.webServer>
   </configuration>

2. Make sure to change {file_mask} parameter to the correct mask of web service that you configured during installation of CMO module. For example, if your web service URL is “http://localhost/mywebservice.stat” you could specify “mywebservice.stat” or “*.stat” instead of this parameter.