Creating Meaningful Dimensions

Thursday, June 23, 2016 @ 12:00

By: Scott Gillis, Lead Consultant – Beyond just adding new segment overlays to existing tables and charts, Sitecore provides a way for us to create our own 'report pages'. The custom page can have any mix of tables, charts, and other display elements that help clarify how the website is behaving to achieve organizational goals.

In addition to just creating new pages, Sitecore is designed at its core as a platform to be extended and built upon. Therefore, a development team working with the business users can even extend the base reporting dimensions by supplementing them with data from other sources and creating new cross-sections of the data that is already collected.

As a quick reminder, 'dimensions' in this context are how the data has been grouped together to then be measured based on some metric. Sitecore provides thirty-four dimensions out of the box and each can be measured by seven different metrics. A list of the metrics and dimensions can be reviewed at


Let's say our Paragon Coffeehouse marketing team wants to understand how customers of different types interact on the site, specifically looking to see if certain customer types are more likely to complete an order or abandon orders based on the entry path to the site. We can further speculate that the customer type is stored in a CRM system and has not been integrated into the Experience Profile (xProfile).

Create Sitecore Artifacts for new Dimension

  • Launch the Marketing Control Panel from the Sitecore Launchpad
  • Expand the content tree to Marketing Control Panel -> Experience Analytics -> Dimensions
  • Right-click on Dimensions
  • From the context menu select Insert and choose Folder
  • Enter a name for the folder in the dialog box
  • Click OK
    Creating Meaningful Dimensions - Image One
  • Right-click the new folder and insert a Dimension
  • In the dialog, provide a name for the dimension. It is proper form to start this name with 'By'
    Creating Meaningful Dimensions - Image Two
  • If you expand your new dimension you will see a default segment is created named 'All'. Feel free to rename the item for easier identification. NOTE: that the Name field used on tables and charts is populated with "All" plus the dimension's name
    Creating Meaningful Dimensions - Image Three
  • For the default segment to become available and start to collect data, it must be deployed. In the ribbon click Review tab, from the available options select Deploy
  • Make a note of the Item ID of the Dimension, as this will be required later
  • This is also a good time to create any additional known segments that will be required as children of the Dimension

Coding Aggregation for a Custom Dimension

After defining the dimension, compiled code needs to be put into place to allow the aggregation process to build the data set for reporting.

The aggregation process requires us to create a single class that inherits from Sitecore.ExperienceAnalytics.Aggregation.Dimensions.DimensionBase or one of its implementations.

There are seven options to inherit from

  • Channel Dimension Base
  • Geo Dimension Base
  • Interval Dimension Base
  • Page Dimension Base
  • Page Event Dimension Base
  • Page URL Dimension Base
  • Visit Dimension Base

Two actions occur in the dimension process. First is that a 'dimension key' is produced. The dimension key is stored in [dbo].[DimensionKeys] of the Reporting database and is then referenced when new segments for the dimension are processed. This can be seen in [dbo].[SegmentRecords]. The dimension key is data point by which the data is being grouped. In my scenario, this would be the customer type from the CRM system. The second action that takes place is the calculation of the metrics. If you recall, Sitecore provides seven named metrics that each represent slightly different data counts per the dimension being viewed. When creating your own dimension processing code, you must take into account how the different metrics should be used and how the business users will interpret them or your reports may end up looking very strange. (At the time of this writing, there is not a way to extend or add new metrics.)

The Sitecore implementations of Dimension Base provide specific key and calculation logic specific to the data needing to be collected. If implementing directly from Dimension Base, you are required only to implement the abstract GetData method. This is the method which the aggregation process calls to record data. This is the method where you would place any business logic, such as retrieving data from other sources, and the filtering inclusion/exclusion logic based on your needs.

The second method, which is optional, is CalculateCommonMetrics. Just as the name applies, this method performs the calculations for the different metrics, allowing you to provide your own logic in how the math is figured. The metric data is calculated per record item, with the summation of values done at the time of reporting.

For our custom scenario, we are interested in how the different customer type's visits go, therefore we've inherited from Visit Dimension Base.

It is important to understand how the metrics for your dimension are calculated, as this has a direct impact on the metric(s) that can be selected when configuring the display of the data. Visit Dimension Base uses the CalculateCommonMetric method as defined in Sitecore.ExperienceAnalytics.Aggregation.Dimensions.DimensionBase and looks like the following:

With the calculating code in place, we now need to make the aggregation process aware of our dimension and code. This requires creating a configuration patch file that patches in two items.

If you forget one or both of these values, then you will see error messages in your log similar to the following:

  • 16236 08:26:16 FATAL [Experience Analytics]: Cannot instantiate dimension <dimension id>.
    Data for this dimension won't be aggregated. Please check configuration.

After deployment, our new aggregation logic will only be applied to new visit information data that is coming in. For the business to review data from historical visits, we will be required to rebuild the reporting database in SQL.

This is done by attaching a clean SQL Analytics database as the secondary reporting database, then performing a reporting database rebuild via http://MY SITE/Sitecore/admin/rebuildreportingdb.aspx. Depending on the amount of data, this could be very time and computing resource intense. It is best to run it during off hours or with the aggregation processes spun off to separate Sitecore servers.

In the next post, I'll walk you through the creation of a dashboard to get this data to the business in a consumable form.

As always, feel free to tweet me questions or comments @thecodeattic or on Sitecore Slack Community as @gillissm.



Scott Gillis, Lead Consultant at Paragon and 2017 Sitecore MVP, has been working with Sitecore for several years. He has a deep passion for helping clients leverage their content and data into powerful new capabilities in Sitecore and has produced successful outcomes as the technical lead on numerous, complex implementations. Recently, Scott has been focusing on helping these clients take advantage of the wealth of data collected by Sitecore Experience Analytics.