Creating The Dashboard

In the post Creating Meaningful Dimensions, we walked through what was needed to aggregate our data for reporting. In this post, I will address getting that data onto the screen for the business to reference.

Setting up new dashboards can only be done via Sitecore Rocks (a user can leverage either the desktop or Visual Studio version.) Due to the need for an additional tool, as well as some other non-standard Sitecore entry steps, a developer or an experienced editor with deep Sitecore knowledge should perform these steps.

  1. Login to Sitecore
  2. From the launch pad open the desktop
  3. Once in the desktop view, you will need to switch to the Core database
  4. Launch Content Editor
  5. Expand the tree to /sitecore/client/Applications/ExperienceAnalytics/Dashboard
  6. Right-click on Dashboard
  7. Select Insert -> Insert from Template
    1. You want to pick a /Sitecore/templates/Common/Folder
  8. Give the folder a name and assign an icon. The icon will be used in the menu of xAnalytics
    Creating The Dashboard - Image One
  9. Open Sitecore Rocks
  10. Open the Core database
  11. Expand the tree to /sitecore/client/Applications/ExperienceAnalytics/Dashboard
  12. Right-click the new folder (created in step 7), Add -> New Item
    1. Search for /sitecore/client/Applications/ExperienceAnalytics/Common/Templates/Branches/Applications/ExperienceAnalyticsReportPage
    2. This OOB branch template provides a child item, PageSettings, and the default style sheet reference via ExperienceAnayltics Stylesheet item
  13. Give a name to the page
    1. This will be your opening dashboard page
      Creating The Dashboard - Image Two
  14. Change the Browser Title field to match what you want shown in the browser tab area
    Creating The Dashboard - Image Three
  15. PageSettings is a folder used to organize all data source elements used by the charts, graphs, and tables on the report page
    1. Right-click on PageSettings, Add -> New Item
    2. In the new item window, search for ExperienceAnalytics, the result set should show a number of items that end in ‘parameters’. These items are used to define the data displayed via charts, graphs, and tables
    3. Click on ExperienceAnalyticsBarChart Parameters
  16. Give it a name
  17. Click OK
    Creating The Dashboard - Image Four
  18. Enter value in the Title field, this value will be shown above the bar graph
  19. Choose a Metric from the dropdown that represents the value being calculated
    1. For example, we want to pick Page Views to understand how many pages each customer type has visited. (e.g. do those that order coffee end up visiting more pages)
  20. (optional) In a complex reporting setup we may want to set the TargetPage field so the user can click through the table to a more detailed viewing of the backing data
    1. This allows us to build out a reporting experience for the user
  21. Under Segments, select the segments created in Step 1
  22. KeysCount field should be set with number of unique keys that should be shown
    Creating The Dashboard - Image Five

The final steps involve adding the bar chart to our report page and connecting it to the parameter item we’ve just completed setting. The following steps will continue to be performed in Sitecore Rocks (via the desktop or Visual Studio version.)

  1. Launch the presentation details for the item by right-clicking the report page, Tasks -> Design Layouts or selecting it and pressing CTRL+U
  2. Click Add Renderings, in the upper left corner of the screen to launch the rendering selector
  3. In the search box, enter ExperienceAnalytics. This will filter to the standard report controls
  4. Click on ExperienceAnaylticsBarChart
  5. Click OK
    Creating The Dashboard - Image Six
  6. Double-click on ExperienceAnalyticsBarChart1 to open up the rendering properties
  7. Find the row named DataSource, click the three dots to open the selector and pick CustomerTypeBarChart
  8. Find the row named PlaceholderKey and confirm the key is Main.Content
    1. If it is not, click the three dots (…) to select the correct placeholder
  9. Once everything is defined, click Close
  10. Save the layout file
    Creating The Dashboard - Image Seven

Now it’s time to see how our customers are performing. Login into Sitecore and, from the launch pad, click Experience Analytics. You’ll notice that the left side menu automatically pulls up the folder we created (1) and it displays the assigned icon. Expanding our folder, we should see our custom reporting page (2) and upon selecting it, our bar chart (3).

Creating The Dashboard - Image Eight

Bibliography of Awesome References

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

[Originally posted at]


Creating Meaningful Dimensions

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

  1. Launch the Marketing Control Panel from the Sitecore Launchpad
  2. Expand the content tree to Marketing Control Panel -> Experience Analytics -> Dimensions
  3. Right-click on Dimensions
  4. From the context menu select Insert and choose Folder
  5. Enter a name for the folder in the dialog box
  6. Click OK
    Creating Meaningful Dimensions - Image One
  7. Right-click the new folder and insert a Dimension
  8. In the dialog, provide a name for the dimension. It is proper form to start this name with ‘By’
    Creating Meaningful Dimensions - Image Two
  9. 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
  10. 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
  11. Make a note of the Item ID of the Dimension, as this will be required later
  12. 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

  1. Channel Dimension Base
  2. Geo Dimension Base
  3. Interval Dimension Base
  4. Page Dimension Base
  5. Page Event Dimension Base
  6. Page URL Dimension Base
  7. 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.

[Originally posted at]

Deciphering the Contact List Puzzle

Sitecore Experience’s List Management tool provides a lot of options to create complex lists of contacts for emails, personalization, and automated engagement plans. Before you start creating hundreds of lists from old spreadsheets, let’s review the basics of how Sitecore List Management works and the puzzle pieces at your disposal to build-out a maintainable list strategy.

The Basic Pieces

Segmented Lists are rules based and dynamic in nature. Therefore, no contact actually belongs to a segmented list until the list is evaluated. Because of this dynamic nature, it is not possible for a user to opt-in or opt-out of a segmented list; they would need to change the contact information that the rule is being evaluated on.

Contact Lists, on the other hand, are static in nature; a contact belongs or does not belong. The static nature means that it is possible for controls to be provided that allow a user to be added or removed via admins (i.e. the list manager) or some form of a subscription control placed on the site.

What does this mean for building lists for emails? It requires a little more planning with some long term payoffs in easily targeting users for emails, personalization, and engagement plans.

When and Why Segmented Lists

Segmented lists are useful when there is a subset of all contact records that should be targeted. You could manually find and add these contact records to a contact list, but that can be time consuming and tedious if there are thousands of contacts to review. This is where Segmented Lists come in handy. During the creation of a segmented list, you define a filter based on the Sitecore Rules Engine with one or more conditions. When the Segmented List is evaluated, such as during an email send or export, all contacts are filtered through the set rules leaving you with only those contacts you wish to engage.

Deciphering the Contact List Puzzle - Image One

The dynamic nature of Segmented Lists allows users to naturally be dropped or added based on their engagement with the organization. Thus, they will receive more accurate and beneficial information from you, creating long-term engagement with the organization.

Finally, Segmented Lists can be exported to a CSV file and a snapshot of the current evaluation of the filter (moment in time) can be converted into a Contact List. The conversion into a Contact List can be used as a starting point for a larger mailing list or even a one-off targeted communication where you may need to know the email recipients at a later time.

When and Why Contact Lists

As I have mentioned, a Contact List is static in nature. Contact records must be explicitly added or removed from this type of list. One can think of a Contact List more as a traditional mailing list that can still be managed in a spreadsheet.

Because of the explicit nature of a Contact List, they can be revealed to site visitors for personal opt-in or opt-out via a subscription control or through the save actions of a Web Forms for Marketers form. (Note that, when using the WFFM to add to a contact list, you must also include the create user or other mechanism to create a contact record or it will throw an error.)

Contact Lists are useful for allowing visitors to self-identify interests by subscribing or unsubscribing to them, as well as for tracking targeted communications.

One Last Piece

The final puzzle piece, before it can all be put together, is that both Segmented and Contact Lists can be assigned ‘include lists’ and ‘exclude lists’. Both must be a Contact List in nature. Exclude Lists are used to indicate that anyone that has subscribed (Contact Lists) or is part of the starting collection (Segmented Lists) should not be evaluated any further. This would prevent this contact record from receiving any messages through this list.

Include Lists, on the other hand, are used by Segmented Lists to determine which contact records should be evaluated through the Segmented List rules that have been setup. By default, Segmented Lists start with the ‘entire database’, i.e. all of the contacts. When working with Contact Lists, the ‘include lists’ help to pre-populate existing contacts. This is helpful when first setting up new subscription lists to make sure that the appropriate people are pre-subscribed.

Building the List Puzzle

I think that the easiest way to understand this is to play out a scenario. Let’s say that the Paragon Coffee marketing team has decided to begin hosting monthly coffee tastings at the warehouse. To make this event cost effective in building out customer loyalty, they cannot send this to all 10,000 contacts. Their plan is to target those customers who have bought $100 or more in products in the previous month. The marketing team are also willing to include individuals who subscribed to the more generic sounding events mailing list. To accomplish this, the marketing group takes the following steps:

  1. Create a Segmented List based on all contacts (entire database). Using a custom segmentation rule, it will filter all of the users who made a purchase greater than or equal to $100 in the past 30 days
    1. They called this: “Hundred Dollar Monthly Purchase Segment”
  2. Create a Contact List called “Paragon Coffee Event Opt-out”, as we are required to track who should not receive the messages
  3. Create a second Contact List called “Paragon Coffee Event Mailer”
  4. As part of the creation of the “Paragon Coffee Event Mailer”, add the “Paragon Coffee Event Opt-out” as an Exclude List source. This will help keep the actual recipients list correct, if for some reason an account ends up on both lists
  5. The “Global Opt-Out” is also added as an Exclude List to confirm that all of the users that have indicated that they wish to receive nothing are properly handled
    Deciphering the Contact List Puzzle - Image Two
  6. During the creation of the “Monthly Tasting Event” scheduled email, the following is done:
    1. “Hundred Dollar Monthly Purchase Segment” list is added as an include
    2. “Paragon Coffee Event Mailer” list is added as an include
    3. “Paragon Coffee Event Opt-out” list is added as an exclude

    Deciphering the Contact List Puzzle - Image Three
    Deciphering the Contact List Puzzle - Image Four

In this way, the email will be sent to everyone who purchased $100 or more in the previous month and those who signed up for the events mailing list, but exclude those who are on the Event Opt-Out list.


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

[Originally appeared on]


MTA Configuration In Sitecore

Email Experience Manager (EXM), formerly Email Campaign Manager (ECM), is a key toolset in completing the engagement cycle with site visitors. A properly managed email campaign will allow you to further engage your site visitors after they have left visiting the site. By leveraging Sitecore to manage this, you a) cut out requirements to purchase and maintain another toolset, b) can leverage site visit data to better target email messages, and c) all data is collected into a single source for well-rounded reporting.

A Little EXM Background

EXM does not come pre-installed in a Sitecore installation. It must be downloaded and installed after the initial site setup. When looking to install, you need to make sure that you install the correct version for your Sitecore instance. A list of all available versions can be found at One thing to note for the advanced editor looking to explore EXM, is that downloads of the products are only available to those who have been awarded a Sitecore Developer Certificate, so talk with your Sitecore Partner or Sales Rep for more information.

I will point out that, in the past year and a half, Sitecore has gotten much better at matching EXM (and WFFM for that matter) versions to that of the core Experience Manager (CMS). Here is a helpful table to assist you pinpoint which version you want.

Sitecore Experience Manager EXM URL
8.1 rev. 151207 (Update-1) 3.2 rev. 160127 (Update-1)
8.1 rev. 151003 (Initial Release) 3.2 rev. 151020 (Initial Release)
8.0 rev. 151127 (Update-6) 3.1 rev. 151213 (Update-2)
8.0 rev. 150812 (Update-5) 3.1 rev. 150811 (Update-1)
8.0 rev. 150621 (Update-4) 3.1 rev. 150811 (Update-1)
8.0 rev. 150427 (Update-3) 3.1 rev. 150703 (Initial Release)
8.0 rev. 150427 (Update-3) 3.0 rev. 150429 (Update-3)
8.0 rev. 150223 (Update-2) 3.0 rev. 150223 (Update-2)
8.0 rev. 150121 (Update-1) 3.0 rev. 150126 (Update-1)
8.0 rev. 141212 (Initial Release) 3.0 rev. 141217 (Initial Release)

How do Emails Send

EXM provides an interface to create emails, schedule sends, build recipient lists, and track read and bounced message data on your emails. It does NOT perform the actual technical send of the email! EXM must call to an actual email sending service, also called a Mail Transfer Agent or MTA.

A default install of EXM is configured for you to purchase sending capabilities directly from Sitecore via the Sitecore App Center. This may be perfect once everything has been elevated into production, but will not be the best solution for a QA or development environment. If you are a super high volume sender, Sitecore’s offering may not be cost effective for your organization.

Thankfully, as with most things in Sitecore, there is usually another option that involves a little extra configuration work, and in this scenario, that would be the ‘UseLocalMTA’ flag.

Setup for a non-Sitecore MTA Usage

  • To be able to send via other Mail Transfer Agents, your Sitecore license must include a specific flag. This is flag is not always included by default, so reach out to your Sitecore sales representative or Sitecore Partner to for more information.
    • If you have configured Local MTA, but have not updated your license file, you may receive an error message similar to the following:
      “The Sitecore App Center password is not set.”
      MTA Configuration in Sitecore - Image One

    Your license does not allow you to use a specific MTA to send messages. Contact your Administrator or Sitecore representative.
    MTA Configuration in Sitecore - Image Two

  • Configure EXM to talk with your chosen MTA provider. The settings are all contained in App_Config \ Include \ EmailExperience \ Sitecore.EmailExperience.ContentManagement.config, which you can happily edit directly…which would be a big Sitecore NO-NO! Instead, use the following patch file that is to be placed into your ‘z.loadlast’ directory in App_Config \ Include. [“The z.what the hell directory” you ask, take a look at my post How Sitecore Config Files Load.]

    [Download from GIST –]

Using Amazon SES as your Mail Transfer Agent

If you are looking for an excellent production alternative to Sitecore’s services, Amazon SES is most likely on your radar. Getting configured for sending is fairly quick, especially when using a patch config file to load your settings. From a development and QA perspective, if you are able to stay under the messaging limits, Amazon SES is an excellent alternative to a standalone SMTP server.

  1. Create a new Amazon Web Services (AWS) account or login to your existing account
  2. From the list of available services pick SES
    1. MTA Configuration in Sitecore - Image Three
  3. Once in SES, we need to verify one or more email address that messages will be sent from. If you are running as a free test account, the email addresses for recipients of the messages must also be verified. Click “Email Addresses” from the left-side menu 
    1. MTA Configuration in Sitecore - Image Four
  4. Create SMTP Credentials, by clicking on “SMTP Settings” in the left-side menu
  5. Click the large blue button for Create My SMTP Credentials in the center of the page 
    1. MTA Configuration in Sitecore - Image Five
  6. Amazon provides a nice wizard that walks you through getting your SMTP Credentials. Follow these steps and be sure to download/copy the username and password that was generated for you 
    1. MTA Configuration in Sitecore - Image Six
  7. Updated the patch config based on the following notes:
    Setting Value
    UseLocalMTA True
    Sleep 500 (if you are running under the test account of AWS, there is a need to delay how quick the relay is)
    SMTP.Server Taken from the Server Name field in step 5
    SMTP.Port 25 (feel free to change to 465 or 587, as supported by Amazon)
    SMTP.UserName Username value from step 6, this is what you should have downloaded. Do NOT use your AWS account name, as it will not authenticate
    SMTP.Password Password value from step 6, this is what you should have downloaded. Do NOT use your AWS account password, as it will not authenticate
    SMTP.AuthMethod LOGIN (this must be in all CAPS)
    SMTP.StartTLS True (as defined in the under SMTP Settings in SES)
  8. Login to Sitecore and send a test email. Make sure the sending address has been verified or you will receive errors

The above gives the basics for email setup using another mail transfer agent. For some of the more complicated setup or to learn more, here are some references to Sitecore’s documentation.

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

[Originally appeared at]