Step 5: Test the Top Filter

View the ProfileKeyFilterTop report and test your new top filter in Sitecore Analytics.

1. In Sitecore Analytics, to refresh your reports, close and then expand the Reports node.

2. Click on your new report: ProfileKeyFilterTop

3. Select a profile key such as Semi-pro using the filter created in my previous blog. All records for the chosen profile key are displayed in your report.

4. Open the Filters Editor window again. You should see your new top filter displayed in the Filters Editor window.

5. Select your top records filter.

6. Click value in the Filter description panel and enter a value such as 5. Click OK to close the Filters Editor window. You should now only see the top 5 records returned for the Semi-pro profile key.

Step 4: Configure your Sitecore Filter Definition Item

When you have created your filter class and updated your SQL query you then configure your Sitecore filter definition item to point to your C# assembly.

1. In the Content Editor, Criteria folder, select your filter definition item.

/sitecore/system/Settings/Analytics/Filters/Criteria/WhereTopRecords

2. In the Type field, enter the correct path to your C# class and assembly.

ChrisTest.sitecore_modules.Cbtest.WhereTopRecords,ChrisTest

namespace                                     class name           assembly

3. Save your changes.

My next post: Step 5 – Test the Top Filter

Step 3: Add a TOP Clause to your SQL Query

To add a filter implementation to a report, you normally add a placeholder to the WHERE clause in your SQL query. However, since the TOP clause appears immediately after the SELECT clause, you need a workaround to implement a Top filter. Use Transact SQL (TSQL) to create a CASE WHEN ELSE statement and embed this into the SELECT clause of your SQL query.

To add a TOP clause to your SQL query.

1. Open your ProfileKeyFilterTop report in the report designer

2. Right click the IPOwners data source and click Edit

3. Copy the following TSQL code into your SQL query directly after the SELECT statement.

top (
  CASE WHEN '{MaxRecords}' = ''
                  THEN 1000
                  ELSE CAST(REPLACE( REPLACE( '{MaxRecords}', 'and (', '' ), ')', '') as integer )
                  END
              )

CAST(REPLACE( REPLACE( '{MaxRecords}', 'and (', '' ), ')', '') as integer )

SELECT
  top (
  CASE WHEN '{MaxRecords}' = ''
                  THEN 1000
                  ELSE CAST(REPLACE( REPLACE( '{MaxRecords}', 'and (', '' ), ')', '') as integer )
                  END
              )
Count(DISTINCT IpOwner.IPOwnerId) AS IPOwnerIdObject, IpOwner.Name,  IpOwner.Country,
Count(DISTINCT Session.GlobalSessionId) AS VisitorCount,
Count(DISTINCT Session.SessionId) AS VisitCount,
Sum(DISTINCT ProfileKey.Value) AS Score,
ProfileKeyDefinition.Name AS Prof

FROM Session
INNER JOIN  Profile ON Session.SessionId = Profile.SessionId
INNER JOIN  GlobalSession ON GlobalSession.GlobalSessionId = Session.GlobalSessionId
INNER JOIN  Ip ON Ip.IpId = Session.IpId
INNER JOIN  IpOwner ON IpOwner.IpOwnerId = Ip.IpOwnerId
INNER JOIN  Browser ON Browser.BrowserId = Session.BrowserId
INNER JOIN  ProfileKey ON ProfileKey.ProfileId = Profile.ProfileId
INNER JOIN  ProfileKeyDefinition ON ProfileKeyDefinition.ProfileKeyDefinitionId =  ProfileKey.ProfileKeyDefinitionId 

WHERE
Session.Timestamp >= @StartDate and
Session.Timestamp <= @EndDate
{MyProfileKey}

GROUP BY IpOwner.Name, IpOwner.Country, ProfileKeyDefinition.Name  

ORDER BY Prof, Score DESC, IpOwner.Name

Step 2: Create your Filter Implementation in Visual Studio

To create a new report filter, you must use Visual Studio and create a new C# class. Alternatively, re-use an existing filter, such as WhereSpecificProfileKey from my last blog. If you do this, re-name and edit the existing C# class file.

· Make sure that your class includes the following references and inherits from the Operator Filter Base class:

· Sitecore.Kernel

· Sitecore.Analytics

public class WhereTopRecords : OperatorFilterBase

using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;
using Sitecore.Analytics.Data.Filters.Filters;
using Sitecore.Analytics.Data.Filters;
using Sitecore.Diagnostics;

namespace <your project name>.sitecore_modules.<your project folder>
{
    public class WhereTopRecords : OperatorFilterBase
    {

        public string value;

        // Methods
        public override void ApplyFilter(SqlCommand sqlCommand)
        {
            Assert.ArgumentNotNull(sqlCommand, "sqlCommand");
            string @operator = base.GetOperator();
            sqlCommand.AddWhereClause("MaxRecords", Value, false);
        }

        public override bool IsApplicable(SqlCommand sqlCommand)
        {
            Assert.ArgumentNotNull(sqlCommand, "sqlCommand");
            return (sqlCommand.HasPlaceholder("MaxRecords"));
        }

        //Properties   
        public string Value
        {
            get
            {
                return (this.value ?? "1000");
            }
            set
            {
                Assert.ArgumentNotNull(value, "value");
                int defaultValue = 1000;
                Int32.TryParse(value, out defaultValue);
                this.value = defaultValue.ToString();
            }
        }

    }
}

// Fields
        public string value;

// Methods
public override void ApplyFilter(SqlCommand sqlCommand)
        {
            Assert.ArgumentNotNull(sqlCommand, "sqlCommand");
            string @operator = base.GetOperator();
            sqlCommand.AddWhereClause("Top", Value, false);
        }

{placeholder}

public override bool IsApplicable(SqlCommand sqlCommand)
        {
            Assert.ArgumentNotNull(sqlCommand, "sqlCommand");
            return (sqlCommand.HasPlaceholder("MaxRecords"));
        }

//Properties   
        public string Value
        {
            get
            {
                return (this.value ?? "1000");
            }
            set
            {
                Assert.ArgumentNotNull(value, "value");
                int defaultValue = 1000;
                Int32.TryParse(value, out defaultValue);
                this.value = defaultValue.ToString();
            }
        }

Step 1: Create a Filter Definition Item

A Sitecore report filter consists of a filter definition item, stored in the filter criteria folder and a C# class containing the filter implementation.

To create a filter definition item:

1. Open the Content Editor and in the content tree navigate to the following location.

/sitecore/system/Settings/Analytics/Filters/Criteria

2. In the ribbon, click Insert from Template. Select the filter template: /System/Analytics/Filter

3. Name your filter WhereTopRecords.

4. In the Header field, enter:

where top records returned

5. In the Text field, enter: 

where top records returned is equal to [value,,,value]

 6. The Type field will contain a reference to your Visual Studio filter implementation. Leave this field blank for the moment.

7. Save your changes.

My next post: Step 2 – Create your Filter Implementation in Visual Studio

Introduction

Welcome to my third Sitecore blog on creating OMS reports.

In this post, I will create a “top” filter that limits the records displayed in a report. To do this you would normally hard code a SQL TOP clause into your SQL query but in this blog I will demonstrate how you can achieve the same result by creating a filter.

A “top” filter could allow an end-user to enter any numerical value of their own, such as top 10 or top 100. This would make it easier for a marketer to see at a glance which leads are the most important to follow up and is better for performance than displaying every record in the database.

We realized that this would be something “nice to have” in the product and the solution presented here is one way of achieving this. However, it is not a typical approach. For example, we don’t recommend the use of TSQL in your SQL queries as this can cause problems when migrating from a SQL Server to an Oracle database. This blog merely demonstrates some of the possibilities available to developers when creating Sitecore OMS reports. As a report analyst, if you have enough in-depth knowledge of the SQL query language and some programming experience, you can create almost any filter or report you need. The only limitations are the contents of your database tables and your own imagination!

Prerequisites

When you create a new filter, you place the logic behind the filter in a C# class file. Therefore to create new filters it is necessary to have some knowledge of C# and Visual Studio.

You also need to install the following:

· Sitecore OMS

· Stimulsoft Report Designer (Stimulsoft Reports.Net 2009.2)

· Visual Studio 2005 or 2008

Optional step: You can add a filter to any existing report but in this blog I will duplicate the ProfileKeyFilter report I created in my previous blog and rename it ProfileKeyFilterTop. This is an optional step which makes it easier to test your filter without affecting you other existing reports. It also means that you are working with the same data sources and SQL query.

Creating a Top Filter

To create a new filter, you need to complete the following steps:

· Create a Filter Definition Item

· Create your Visual Studio Filter Implementation

· Add a Top Clause to your SQL Query· Configure your Sitecore Definition Item

· Test your Top Filter

My next post: Step 1 – Create a Filter Definition Item

Step 5: Test your Filter

View your new report and test your filter in Sitecore Analytics.

1. In Sitecore Analytics, to refresh your reports, close and then expand the Reports node.

2. Click on your new report: ProfileKeyFilter

3. You should see an unfiltered report that displays all profile keys in the Nicam site.

4. Click Filter. You should see your new filter displayed in the Filter Editor window.

5. Select the filter and then click specific value.

6. The Select Profile Key dialog box, displays all profiles and profile keys. Select a profile key, such as Semi-pro.

7. Click OK in the Select Profile Key dialog box and the Filter Editor window. You should see the following report filtered by the Semi-pro profile key:

You can now use this filter this report to show the top scores and organizations for any given profile key in the Nicam site.

Step 4: Configure your Sitecore Filter Definition Item

When you have created your filter class and added a placeholder variable to your SQL query you then must configure your Sitecore filter definition item to point to your C# assembly.

1. In the Content Editor, Criteria folder, select your filter definition item.

/sitecore/system/Settings/Analytics/Filters/Criteria/WhereSpecificProfileKey

2. In the Type field, enter the correct path to your C# class and assembly.

ChrisTest.sitecore_modules.Cbtest.WhereSpecificProfileKey,ChrisTest

namespace                                     class name                    assembly

3. Save your changes.

My next post: Step 5 – Test your Filter

Step 3: Add a Placeholder to your SQL Query

To add a filter to a report, you must add a variable to the SQL query in your report .mrt file that has the same name as the placeholder in your C# class. If you open any Sitecore report that contains filters, you can see all the filter variables below the WHERE clause.

To add your new filter to the Profile Key Filter report:

1. In the Report Designer, click Open Report and locate the file ProfileKeyFilter.mrt.

C:\Inetpub\wwwroot\<your site>\WebSite\sitecore\shell\Applications\Analytics\Reports

2. First create a variable for your placeholder. In the Dictionary panel, click New Item, New Variable.

3. In the Name field enter MyProfileKey and enter the same value in the Alias field. Keep the Type as string and click OK.

4. Next, add your variable to the SQL query. Click IPOwners and then click Edit to edit the Data Source. This enables you to make changes directly to your SQL query.

5. Add your placeholder {MyProfileKey} to the WHERE clause of your SQL Query.

6. Click OK and save your changes in the report designer.

My next post: Step 4 – Configure your Sitecore Filter Definition Item

Step 2: Create your Filter Implementation in Visual Studio

To create a new report filter you must use Visual Studio and create a new C# class.

Create a new C# Class file

1. Create a new C# project.

2. Create a new C# Class .cs file to add to your project.

3. Make sure that you add the following references to your class:

· Sitecore.Kernel

· Sitecore.Analytics

4. Name your class WhereSpecificProfileKey.

5. Ensure that your new class inherits from the Operator Filter Base class.

public class WhereSpecificProfileKey : OperatorFilterBase

using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;
using Sitecore.Analytics.Data.Filters.Filters;
using Sitecore.Analytics.Data.Filters;
using Sitecore.Diagnostics;

namespace ChrisTest.sitecore_modules.Cbtest
{
public class WhereSpecificProfileKey : OperatorFilterBase
  {
    // Fields
    private string profileKeyId;
      // Methods
    public override void ApplyFilter(SqlCommand sqlCommand)
          {
            Assert.ArgumentNotNull(sqlCommand, "sqlCommand");
            sqlCommand.AddWhereClause("MyProfileKey", "ProfileKeyDefinition.ProfileKeyDefinitionId = '" + this.ProfileKeyId + "' ", base.Except);
          }
        public override bool IsApplicable(SqlCommand sqlCommand)
          {
            Assert.ArgumentNotNull(sqlCommand, "sqlCommand");
            return (sqlCommand.HasPlaceholder("MyProfileKey") );
          }
    // Properties
    public string ProfileKeyId
        {
          get
          {
          return (this.profileKeyId ?? string.Empty);
          }
          set
        {
          Assert.ArgumentNotNull(value, "value");
          this.profileKeyId = value;
        }
      }
    }
}

using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;
using Sitecore.Analytics.Data.Filters.Filters;
using Sitecore.Analytics.Data.Filters;
using Sitecore.Diagnostics;

private string profileKeyId;

public override void ApplyFilter(SqlCommand sqlCommand)
        {
            Assert.ArgumentNotNull(sqlCommand, "sqlCommand");
            sqlCommand.AddWhereClause("MyProfileKey", "ProfileKeyDefinition.ProfileKeyDefinitionId = '" + this.ProfileKeyId + "' ", base.Except);
        }

public override bool IsApplicable(SqlCommand sqlCommand)
{
    Assert.ArgumentNotNull(sqlCommand, "sqlCommand");
    return (sqlCommand.HasPlaceholder("MyProfileKey") );
}

// Properties
public string ProfileKeyId
{
    get
    {
    return (this.profileKeyId ?? string.Empty);
    }
    set
    {
    Assert.ArgumentNotNull(value, "value");
    this.profileKeyId = value;
    }
}