Extend Sitecore Engagement Plan UI to assign contacts to an engagement plan state

The default Sitecore Engagement Plan currently supports the following option to assign users/contacts to an engagement plan state

  • Add from CSV File
  • Add a Sitecore user
  • Add all Members of a Sitecore Role
  • Add a Segment

Out off all those options only the segment option have the capability of assigning existing contacts to an engagement plan state.

However, what if we would like to import contacts from a CSV file there’s no option to do so, the Add from CSV file will import the data as Sitecore users instead of contacts.

We would need to modify the UI in order to achieve the functionality that we’re aiming for. To do so first we would need to figure which file to modify.

As the UI is using Silverlight it’s a bit difficult to figure which file we need to modify, however searching for the “Welcome to the Import Contacts Wizard” text under the /sitecore  folder reveals that this file seems to be the correct one

Further inspecting the code inside that file and tinkering with it a bit confirms that this is the correct file to modify.

We will not modify the existing Sitecore file, instead we will use the Override folder in order to apply our modification to the existing XML control. To do this copy and paste the existing ImportVisitors.xml file to the override folder

You can put the file directly inside the Override folder, but it’s good practice to replicate the original folder paths so you know which file you’re overriding. After we now know which file to modify we can start modifying the default behaviour of that XML control.

The modified ImportVisitors.xml


The code beside file


The end result

Source Code is available in GitHub



Sitecore Server Role Checker Tool

When configuring Sitecore in a distributed environment, you typically have more than 1 server in the production environment configured as a different roles (CM, CD, Processing, Reporting Service, etc).

More often than not I’ve noticed that issues are raised due to misconfiguration rather than implementation itself. You then go to Sitecore documentation site and check the configuration for each of the server that you’ve setup to see if there’s anything that you miss.

In the 8.0 documentation you would need to read a long list of tables containing information which config files that you need to enable/disable.

Since the 8.1 release, these steps are simplified with Sitecore providing us an excel spreadsheet file as a guide to enable/disable the config files depending on the role(s) that you want to setup. These steps are manual though and highly likely that we will miss one or two config files and could cause some issues down the line.

With the number of projects that you need to review, this task will start eating up your time and should really be automated. Some might have already done so and create a little tool tucked away somewhere.

I’ve decided to create my own version of the tool called Sitecore Server Role Checker, can’t be more obvious than that 🙂

How does it work?

This tool would basically uses a converted csv format from the Sitecore official spreadsheet guide and read the configuration based on your selected roles. It currently supports the following Sitecore version

  • 8.1 update 3
  • 8.2 initial release
  • 8.2 update 1
  • 8.2 update 2

Only those version is supported as those are only the spreadsheet available for now.

How do I use it?

Follow this simple steps

  1. Choose your Sitecore version
  2. Choose your search engine provider
  3. Browse to your website folder
  4. Tick your intended role(s) for this particular Sitecore instance
  5. Click the Analyze button

It would then go through each of your configuration files and report if there’s any config files that should be enabled/disabled.

Through the tool you can also quickly disable/enable those config files.

What it doesn’t do

  • Check if your config files is updated accordingly, e.q:
    • Changing robot detection handler in CM
    • Configuring remote reporting service url
    • etc
  • Check the configuration files for WFFM, EXM.. yet
  • Make you coffee

Where can I get it?

The code is available in Github

Note that this tool is not deeply tested, if you have any issues or suggestions with the tool then raise a ticket in Github or do a PR

update: 22 February 2017

The tool is now available at Sitecore Marketplace

Sitecore SOLR index update strategies in a scaled environment

Sitecore by default ships with two main search provider which is Lucene or SOLR.

I will not delve too much on which one you should use as that’s been covered in https://doc.sitecore.net/sitecore_experience_platform/setting_up__maintaining/search_and_indexing/indexing/using_solr_or_lucene

I’d like to highlight some of the points mentioned in the article, where using SOLR is mandatory:

  1. You have a dedicated processing server
  2. You have multiple CM servers

The main thing here is that if sitecore_analytics_index exist in multiple servers then you would need to use SOLR. But since all the indexes are now in a centralized server, what’s the index update strategies for SOLR would be?

Typically in this setup you would set

  • CM as the indexing server
    • will perform index rebuild
    • Set the index update strategies as you fit (except manual)
  • CD only reads from index
    • Does not perform index rebuild
    • Set the index update strategies to manual

If you have multiple CM server then you can set one of the CM as the one that perform index rebuild while the other one only reads from the index.


Rebuild sitecore_analytics_index contact data

There’s been an interesting question around how to rebuild the sitecore_analytics_index but specifically only for contact data.

As you’ve probably know that sitecore_analytics_index is not available to be indexed manually – go to the indexing manager in the control panel if you want to check. This is because the index is configured using an observer crawlers.

However there are ways to manually rebuild the sitecore_analytics_index. The example given in that seems to be specifically about rebuilding the interactions documents while what we want is to build the contacts.

I gained some hints from the provided example though, let’s have a look at the following code.

In particular this line

I then go to the handy showconfig.aspx page to find the following

Which shows the processingPools configured for the aggregation processes. From there I can spot the contact element definition which seems to be the one that I’m looking for and start building the code for it.


Depending on your needs, you might want to only reindex known contacts for example. You can take the above example and adjust it yourself.


Sitecore 8 – Extending Experience Profile – Part 4 – Displaying Specific Interactions Data

How to display specific interaction data

For this example, we would like to have a custom list in the Experience Profile where it listed the triggered page event when the site visitor downloaded a PDF file.

End result:



How to set this up

Source code link is available at the end of this post.

How to setup a new page event

First we need to create a page event through the content editor, we can do so by going to the /sitecore/system/Settings/Analytics/Page Events

In the below screenshot I’ve created a page event called “Download PDF File”



How to assign page event to a media item

There’s a tutorial on how to this on Sitecore documentation site

I’m using a page event rather than goal for this POC because this event “download a pdf” doesn’t necessarily lead to a conversion but more about the actions that the site visitors took that we want to be aware of.

In the screenshot below I’ve assigned the pdf files in the media library with my custom page event.


Now if there’s a site visitors that download the specified files on the website, Sitecore will trigger the page event and store the information in MongoDB which later on we will extract and display it in the Experience Profile.

How to setup the custom tab in Experience Profile

The content tree


We define three column to be displayed on the ListControl rendering.


The full list of the renderings


The SubPageCode rendering links to a javascript file downloadedpdffiles.js which will be executed when this item is loaded into the tab.

We can control the page size -the amount of records returned by the server-  in the GenericDataProvider properties.

How to register a new processors for the Experience Profile

Jonathan Robbin’s blog post explain it nicely on what this processors is doing.







Register our custom processors


notice that the sorting and paging is already built in the framework.

Register our custom result transformer



Wire things together

As with the previous post, when the DownloadedPdfFilesPanel item is loaded we will trigger an API call to request the data to be displayed in the list control

The javascript file that’s responsible to do this is the downloadedpdffiles.js

The difference here compared to the previous post when triggering the API call is that we specify the /intel/downloadedpdffiles in the url which Sitecore recognize to be a special route. This route will try to run donwnloadedpdffiles pipelines that we define earlier in the config file.

An example of the API response




Source code

Source code is available in Github

Sitecore 8 – Extending Experience Profile – Part 3 – Displaying Contact Facet Collection Property

How to display contact facet collection property

End result:


How to set this up

Source code link is available at the end of this post.

How to setup the custom contact facet

Similar to what we’ve done in the first post, the only difference here is that we are using collection property instead of simple properties.


The  updated TC.Sitecore.Analytics.Model.config file

note that we need to register our INewsletterElement as well in order for Sitecore to know which type to resolve during runtime.

An example of how the data is being stored in MongoDB



How to setup the web API controller

The updated InitializeRoutes.cs


The updated CustomContactController.cs


The main reason why we are returning as a ResultSet object here is that the list control rendering expects the returned data in a specific JSON structure.

While going through this I thought of the performance implications if we have a lot of data where we should ideally implement pagination when querying against MongoDB. For this POC, this works fine as for newsletters typically the users won’t have thousands of records to be displayed .

An example on how to implement pagination will be provided in the next post.


How to setup a custom tab in Experience Profile

The content tree


Under the NewsletterSubscriptionPanel item you can that there’s NewsletterSubscriptions which based on ListControl template, under that we have the NewsletterName which is using the ColumnField template.

When we use the list control rendering, we can specify what columns are there in the list control and bind the value with a specific property name returned from the API



The full list of the renderings used


note that there’s “more” button assigned to the layout, but this didn’t actually being used. That’s for future improvements when we implement pagination.


Wire things together

As with the previous post, when the NewsletterSubscriptionPanel item is loaded we will trigger an API call to request the data to be displayed in the list control

The javascript file that’s responsible to do this is the newslettersubscriptions.js


An example of the API response



note that it has to return the response in a specific JSON structure that the list control can consume.


Source code

Source code is available in Github

Sitecore 8 – Extending Experience Profile – Part 2 – Displaying Contact Facet Simple Properties

How to display contact facet simple properties

End result:


There’s a good reference on how to create a custom tab in Sitecore Experience Profile on Jonathan Robbins blog post,  I recommend you go and read it through.

How to set this up

Source code link is available at the end of this post.

How to setup the custom contact facet

There’s a good reference on Sitecore documentation site on how to do so.

In my custom facet I only have two properties, which is the HospitalName and the ProfessionName.





And the config patch file to register this custom facet



To fillout the data in the custom facet I’ve setup a page to do this



How to setup the web API controller

First we need to register our custom route to our custom controller



In our custom controller, we just return the custom facet that contains all the properties that we want to display in Experience Profile



Finally we add the InitializeRoutes class to the pipeline



How to setup a custom tab in Experience Profile

I will not go in detail on how I setup the content tree as the reference I’ve provided should give you an idea on how to set it up and I’ll be providing the source code at the end of this post.

This is the content tree in the core database that I’ve setup in order to display those 3 tabs


The first tab which is the Profession tab will be displaying the custom field from the custom contact facet that I’ve setup.

The rendering items


Wire things together

To display this information, after our Profession tab is loaded in the Experience Profile we would need to call our CustomContactController class to retrieve the data.

The code that’s responsible to do this is the profession.js that is set in the SubPageCode rendering control in the ProfessionPanel layout. This javascript file is executed when the ProfessionPanel item is loaded into the Profession tab




The script basically calls an API method in the server which then gives back the response in a JSON format which we then assign to the controls defined in the ProfessionPanel item layout.


This is the full url it’s trying to access http://habitat.dev.local/sitecore/api/ao/v1/contacts/02b2e6c4-d38a-4e30-a18e-b4a31b63907d/customfields/

It’s passing the current contact id and a specific url ‘customfields’ which we route to our custom web API controller. It will then use the cintelUtil helper to bind the data to the text controls defined in our ProfessionPanel layout.


Source code

Source code is available in Github