Manual Installation - EPiServer CMO 1.0

Installation of EPiServer CMO 1.0 for EPiServer CMS 5 R1 SP3 and EPiServer CMS 5 R2 is done manually by following the instructions below. This document describes how to install, upgrade and delete EPiServer CMO 1.0 for EPiServer CMS 5.1.422.267 and 5.2.375.7.

Table of Contents

• Prerequisites
• Module Package Content
• Manual Installation
• Live Monitor Configuration
• Thumbnail Service Configuration
• Aggregation Service Configuration
• Statistics Handler Configuration

Prerequisites

The following presquisites exist for EPiServer CMO:

• System requirements for EPiServer CMO 1.0 on EPiServer CMS 5.1.422.267 (EPiServer CMS 5 R1 SP3)
• System requirements for EPiServer CMO 1.0 on EPiServer CMS 5.2.375.7 (EPiServer CMS 5 R2)

Module Package Content

The CMO.zip file contains the following:

• Bin folder contains EPiServer CMO assemblies and license file for web gauge controls.
• Lang folder contains UI texts in XML files.
• CMO folder contains all pages and user controls of CMO module.
• EPiServer.Cmo.Database.sql file is the script to create CMO database objects and add default configuration data.
• Files for the installation of the aggregation service.

Manual Installation

1. Create EPiServer CMO database. Make sure that your user account has permission to create and manage the database. Run SQL Server Management Studio, connect to the database engine server. Right-click on the Databases folder and select New Database. Define the database name and leave the database owner as default.
2. Create the EPiServer CMO data structures and select the created CMO database. Open the file EPiServer.Cmo.Database.sql file in Microsoft SQL Server Management Studio and execute it in the querty window. The SQL script will create the CMO tables, stored procedures and add default configuration data.
3. Create and configure the SQL server login for CMO module. Right-click on server Security node, select New Login. Define the login name and authentication type. Enter a password if you choose SQL Server authentication. Unselect Enforce password expiration, if you don’t plan to change the password periodically. On the User Mappings tab select CMO database and define db_owner and public role for the CMO database.
4. Select the EPiServer CMS site where you want to install EPiServer CMO. Upgrade the site configuration and change the target framework to .NET 3.5. The easiest way is to use Microsoft Visual Studio 2008 or higher. Do this by selecting Open Web Site from the File menu,  then select Property Pages in the site context menu. And finally, update Target Framework in the Build tab.
5. Define the database connection string for EPiServer CMO. Open the connectionStrings.config file from site root folder. Add a new connection string in Entity Framework format. See the example connection string below. Update it with your specific parameters.
6. Copy assemblies and license files from the bin package folder to the bin folder of the EPiServer CMS site.
   <add name="CmoEntities" connectionString="provider connection string=&quot;Data Source=.\sqlexpress;Initial Catalog=Cmo;Integrated Security=False;User ID=dbUserCMO;Password= dbUserCMO;Connect Timeout=10&quot;;metadata=res://*/Entities.CmoModel.csdl|res://*/Entities.CmoModel.ssdl|res://*/Entities.CmoModel.msl;provider=System.Data.SqlClient" providerName="System.Data.EntityClient" />
7. Copy the UI text files from the lang package folder to the lang folder of the EPiServer CMS site.
8. Copy the CMO package folder to the root folder of the EPiServer CMS site.
9. Update web.config file of the EPiServer CMS site:
   9.1. Add the following string to /configuration/system.web/compilation/assemblies node.
   <add assembly="System.Data.Entity, Version=3.5.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
   9.2. Register CMO tag prefix in /configuration/system.web/pages/controls node.
   <add tagPrefix="cmo" namespace="EPiServer.Cmo.UI.Units" assembly="EPiServer.Cmo.UI"/>
   9.3. Register CMO HTTP module. Add the following string to /configuration/system.web/httpModules node.
   <add name="CMOModule" type="EPiServer.Cmo.Cms.HttpModule.Module, EPiServer.Cmo.Cms" />
   If you use IIS7, add the module registration also to /configuration/system.webServer/modules node.
   <add name="CMOModule" type="EPiServer.Cmo.Cms.HttpModule.Module, EPiServer.Cmo.Cms" preCondition="managedHandler" />
   9.4. Register HTTP handler for web gauges. Add the following string to /configuration/system.web/httpHandlers node as the first child node.
   <add verb="GET" path="GaugeHttpHandler.axd" type="ComponentArt.Web.Visualization.Gauges.GaugeHttpHandler, ComponentArt.Web.Visualization.Gauges" />
   If you use IIS7, add the following string to /configuration/system.web/httpHandlers node as the first child node.
   <add verb="GET" name="GaugeHttpHandler" path="GaugeHttpHandler.axd" type="ComponentArt.Web.Visualization.Gauges.GaugeHttpHandler, ComponentArt.Web.Visualization.Gauges" />
   9.5. Add Chart Handler configuration into /configuration/appSettings.
   <add verb="GET,HEAD" path="ChartImg.axd" type="System.Web.UI.DataVisualization.Charting.ChartHttpHandler, System.Web.DataVisualization, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
   If you use IIS7, add Chart Handler configuration into /configuration/appSettings.
   <add verb="GET,HEAD" name="ChartImageHandler" path="ChartImg.axd" type="System.Web.UI.DataVisualization.Charting.ChartHttpHandler, System.Web.DataVisualization, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
   9.6. Register Thumbnail Handler. Add the following string to /configuration/system.web/httpHandlers
   <add path="thumbhandler.axd" verb="*" type="EPiServer.Cmo.Cms.ThumbnailHandler.CmoThumbnailHandler" />
   If you use IIS7, the following string should be placed here: /configuration/system.webServer/handlers
   <add name="ThumbnailHandler" path="thumbhandler.axd" verb="*" type="EPiServer.Cmo.Cms.ThumbnailHandler.CmoThumbnailHandler" resourceType="Unspecified" requireAccess="Script" />
   9.7. Register Cached Image Service Handler. Add the following string to /configuration/system.web/httpHandlers
   <add verb="GET" path="cachedimageservice.axd" type="ComponentArt.Web.Visualization.Charting.CachedImageService,ComponentArt.Web.Visualization.Charting" />
   For IIS7 (/configuration/system.web/httpHandlers):
   <add verb="GET" name="cachedimageservice" path="cachedimageservice.axd" type="ComponentArt.Web.Visualization.Charting.CachedImageService,ComponentArt.Web.Visualization.Charting" />
10. Define the EPiServer CMO configuration parameters on the CMO Settings page in Admin mode. If the CMO Settings page is not accessible, copy the CMO folder from the root directory of the EPiServer CMS site to ‘your\relative\path\to’ location.
11. Change Internet Explorer security settings (only if Enhanced Security Configuration is turned on).
    11.1. Add the EPiServer CMS website to the trusted websites.
    11.2. Important! Add about:blank website to the trusted websites.
12. Install and configure Aggregation service.
13. Install and configure Statistics Handler service.
14. Check that the CMS site configuration file and Thumbnail service configuration files contain the same “secretkey” value. Value can be any string, but it must be equal in both files.  <appSettings>
    <add key="secretkey" value="1E73FFB0-0F78-4e8e-8D15-3F11B979B5A9"/>
  </appSettings>


Live Monitor Configuration

Does your site have multiple bindings? Read more about how to configure Live Monitor for websites with multiple bindings.

Live monitor utilizes its own statistic gathering handler which could store page-visitor statistics either in the CMO database or in a separate database. Live Monitor utilizes the Silverlight 3  application to display site visitor activity on the Live Monitor page. Configure Live Monitor by following the steps below:

1. You can use CMO database for Live Monitor, but if for some reason you want to use separate database for Live Monitor – create new database and configure login.
2. Execute “LiveMonitorDatabase.sql” script in the target database.
3. Configure scheduled database job: stored procedure "epitraceMaintenance" needs to be set-up to run at least every 24 hours. The stored procedure removes information about old visits rebuilds indexes on the epitraceHits table.
4. Add "CmoLiveMonitor" connection string to the site:
   <add name="CmoLiveMonitor" connectionString="Data Source=.\sqlexpress;Initial Catalog= Cmo;Integrated Security=False;User ID=dbUserCMO;Password= dbUserCMO;Connect Timeout=10" providerName="System.Data.SqlClient" />
5. Update web.config file of EPiServer CMS site:
   5.1 Add service section to /configuration/system.serviceModel/services  node: 
   <service behaviorConfiguration="EPiServer.Trace.Services.TraceServiceBehavior" name="EPiServer.Cmo.Cms.Trace.Services.CmoTraceService">
<endpoint address="" binding="basicHttpBinding" contract="EPiServer.Trace.Services.ITraceService" />
<endpoint address="mex" binding="mexHttpBinding" contract="IMetadataExchange" />
</service>
   5.2 Add behavior section to /configuration/system.serviceModel/behaviors/serviceBehaviors :
   <behavior name="EPiServer.Trace.Services.TraceServiceBehavior">
      <serviceMetadata httpGetEnabled="true"/>
      <serviceDebug includeExceptionDetailInFaults="false"/>
</behavior>
   5.3 Add (edit)  “serviceHostingEnvironment “section (/configuration/system.serviceModel node):
   <serviceHostingEnvironment aspNetCompatibilityEnabled="true" />
   5.4 Add “Location” sections to /configuration node:
   <location path="CMO/Trace">
      <system.web>
        <authorization>
          <allow roles="WebEditors, WebAdmins, Administrators"/>
          <deny users="*"/>
        </authorization>
      </system.web>
      <system.webServer>
        <handlers>
          <remove name="svc-Integrated" />
          <add name="svc-Integrated" path="*.svc" verb="*" type="System.ServiceModel.Activation.HttpHandler, System.ServiceModel, Version=3.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" resourceType="Unspecified" preCondition="integratedMode" />
        </handlers>
      </system.webServer>
    </location>
    <location path="CMO/Trace/Handlers">
      <system.web>
        <authorization>
          <allow users="*"/>
        </authorization>
      </system.web>
    </location>
6. Make sure you have .xap silverlight MIME type configured on your website.
   If you haven’t – add a new MIME type:
   File name extension:                      “.xap”
   Mime type:                                        “application/x-silverlight-app”
   How to add new MIME under IIS6:
   http://www.hosting.com/support/dedicated/IIS/newmime/
    How to add MIME type under IIS7:
   http://technet.microsoft.com/en-us/library/cc725608%28WS.10%29.aspx
   Live Monitor now should work.

Thumbnail Service

Installation

Thumbnail service is a windows service application used for page thumbnail generation.

1. Create folder where thumbnail service will be installed. Default installation folder is [Path to your EPiServer installation]\ Shared\ Services\ Thumbnail Service, for example:
   C:\Program Files\ EPiServer\ Shared\ Services\ Thumbnail Service.
2. Copy all files from Thumbnail Service folder to service installation folder. Copy log4net.dll assembly from “bin” package folder to service installation directory.
3. Service can be installed using standard .NET framework utility InstallUtil. By default InstallUtil can be fiund in .NET Framework 2 folder c:\Windows\Microsoft.NET\Framework\v2.0.50727
   Run command:
   InstallUtil.exe [Path to your thumbnail service files]\IECaptSvc.exeIt is preferred to create a local user and run the service as that user.

Configuration

You can update “secretkey” parameter in appSettings section. This string is used to decrypt credential to login to CMS site.
CMS site must contain the same setting in web.config file:
  <appSettings>
    <add key="secretkey" value="1E73FFB0-0F78-4e8e-8D15-3F11B979B5A9"/>
  </appSettings>

You can also change WCF settings for service, for example change service port. See WCF configuration reference for that.
 

Service has to be restarted after configuration changes.
Service configuration file contains default service configuration and is included to module package.

Removing Service

Run following command to remove Thumbnail service using standard framework utility:

Aggregation Service

Aggregation service is windows service application which aggregates CMO statistics data in defined time intervals for defined CMO instances .

Following files should be deployed:

• EFExtensions.dll
• EPiServer.Cmo.AggregationService.exe
• EPiServer.Cmo.AggregationService.exe.config
• EPiServer.Cmo.Core.dll
• log4net.dll

The default installation folder is [Path to your EPiServer installation]\ Shared\ Services\ CMO Aggregation Service\. For example: C:\Program Files\ EPiServer\ Shared\ Services\ CMO Aggregation Service\.

Aggregation service can be installed and uninstalled using standard framework utility:

By default Aggregation service is installed with Automatic startup type and logs on as Local service.

Configuration

Service and aggregation settings should be defined on CMO Settings page in CMS Admin mode on Data Aggregation tab. Database connection parameters are defined in connection strings section using ADO.NET Entity Framework format.

User can define the number of connection strings to various CMO sites and aggregation service will process data for all available CMO instances. Each connection string must have unique name:
<connectionStrings>  
   <add name="CmoSite1" connectionString="metadata=res://*/Entities.CmoModel.csdl|res://*/Entities.CmoModel.ssdl|res://*/Entities.CmoModel.msl;provider=System.Data.SqlClient;provider connection string=&quot;Data Source=.\EPISERVER;Initial Catalog=CmoSiteDB1;Integrated Security=True;MultipleActiveResultSets=True&quot;" providerName="System.Data.EntityClient" />  
   <add name="CmoSite2" connectionString="metadata=res://*/Entities.CmoModel.csdl|res://*/Entities.CmoModel.ssdl|res://*/Entities.CmoModel.msl;provider=System.Data.SqlClient;provider connection string=&quot;Data Source=.\EPISERVER;Initial Catalog=CmoSiteDB2;Integrated Security=True;MultipleActiveResultSets=True&quot;" providerName="System.Data.EntityClient" />
</connectionStrings>
Application logging can be configured in application configuration file. See more details about log4net configuration here: http://logging.apache.org/log4net/. By default logging is configured to write logs to debug output:

<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="AggregationService.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>
Note: Service can output log data to files. To enable logging to file you need to uncomment RollingLogFileAppender option of <root> node in service configuration file, grant Modify permission on aggregation service folder (by default C:\Program Files\ EPiServer\ Shared\ Services\ CMO Aggregation Service\) to user used to run aggregation service (by default Local service).

Removing service

Aggregation service can be installed and uninstalled using standard framework utility:

Statistics Handler Configuration

CMS pages related to any active campaign contain injection which makes user browser to send reuqests to statistics handler. Statistics handler processes statictis data coming from users and save raw visits log to statistics storage.

Note: Statistics collecting requires the Friendly URL Rewriter module as the injection is done by the handler of this event.

Statistics data handling

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

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

Statistics handler deployment and configuration

1. Create new web site to host statistics handler. If you need, hander can be added to existing web site.
2. Copy EPiServer.Cmo.Core.dll, EFExtensions.dll and log4net.all files to bin directory of web site.
3. If the Web site does not already have a Web.config file, create one under the root of the site.
4. Configure database connection for data model using ADO.NET Entity Framework format. Add 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. Register Statistics handler for IIS (see details in “ HANDLER REGISTRATION FOR IIS” section of this document).
6. You may 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 CMO Settings page in CMS Admin mode on General settings tab. Statistics handler use Cache time out parameter.
8. To properly detect modern browsers few more steps needed. In sites root folder create App_Browsers subfolder and put there browser definition files listed below:
   For Safari version 3.0 and above
   File name: safari.browser
   File content:
   <browsers>
 <browser id="Safari3Plus" parentID="Safari1Plus" >
  <identification>
   <userAgent match="Version/(?'version'(?'major'\d+)\.(?'minor'\d+[\.\d+]*)\w*)\s+Safari" />
  </identification>
  <capture>
  </capture>
  <capabilities>
   <capability name="majorversion" value="${major}" />
   <capability name="minorversion" value="${minor}" />
   <capability name="version" value="${version}" />
  </capabilities>
 </browser>
 <browser refID="Safari1Plus" >
  <capabilities>
   <capability name="browser" value="Safari" />
  </capabilities>
 </browser>
</browsers>
   For Google Chrome
   File name: chrome.browser
   File content:
   <browsers>
 <browser id="GoogleChrome" parentID="Safari1Plus">
  <identification>
   <userAgent match="Chrome/(?'version'(?'major'\d+)\.(?'minor'\d+\.\d+).\d+)" />
  </identification>
  <capture>
  </capture>
  <capabilities>
   <capability name="browser"        value="Chrome" />
   <capability name="majorversion"   value="${major}" />
   <capability name="minorversion"   value="${minor}" />
   <capability name="version"        value="${version}" />
  </capabilities>
 </browser>
</browsers>
   Also, because of internal ASP.NET User-Agent caching we need to add parameter in web.config:
   <system.web>
    <browserCaps userAgentCacheKeyLength="128" />
9. If you need to have debug logs, you can define logging configuration. See details about log4net configuration here: http://logging.apache.org/log4net/.
   Sample configuration with DebugOutput 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>

Handler Registration for IIS

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

Register handler for IIS 6

In the application's Web.config file, create an httpHandlers section.
<configuration>
  <system.web>
    <httpHandlers>
      <add verb="GET" path="{file_mask}" type="EPiServer.Cmo.Core.Statistics.StatisticsHandler, EPiServer.Cmo.Core"/>
    </httpHandlers>
  </system.web>
</configuration>

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.

Configure IIS to forward the request for ”*.stat” requests to ASP.NET.

Register handler for IIS 7 running in Classic mode

In the application's Web.config file, create an httpHandlers section.
Create a handlers element in the system.webServer section.
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>
Replace FrameworkPath with the correct path to the Aspnet_isapi.dll file.
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.

Register handler for IIS 7 running in Integrated Mode

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>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.