Category Archives: Tips & Best Practices

Sitecore 8 – Create a custom personalization rule

Sitecore OOTB comes with tons of personalization rules that we can use, however there might be times where we need to create a custom rule condition that fits to the client business requirements.

Luckily with Sitecore framework that’s known easy to extend, we can easily achieve this.

Here’s the steps to create a custom personalization rule:

1.Register the tag

First of all we need to create a new tag item under /sitecore/system/Settings/Rules/Definitions/Tags


2. Register a new rule element

Create a new element folder in /sitecore/system/Settings/Rules/Definitions/Elements


3. Create a new personalization condition rule


Here I’m creating a new rule and calling it “Specific Template Name” which will do what exactly that, checking if the current context item is based on a specific template name – not really useful in real world scenario but this post is about how to setup a custom personalization rule 🙂

In the newly created rule we need to set the Text and Type fields

Text field contains the text that we’re going to present to the content author, here’s the following text that I use

the [TemplateName, StringOperator,,compares to] represents the format of input that we want to get from the content author. It follows the following format

  • OperatorId, defines the public property of the class where we want to assign the value coming from the content author input
  • StringOperator, the built-in macro that we want to use to get the input from the user. In this case this will be a string comparation operation
  • blank, this parameter will depend on the type of macro that we use, this could be a default text value if we are using the default macro,  it could be a default start path if we’re using the Tree macro  – think of it like setting a field source when we’re building a template in Sitecore. A full list of macros can be found in /sitecore/system/Settings/Rules/Definitions/Macros
  • compares to, the last parameter is the text representation that we want to show to the content author, this value is clickable and when clicked Sitecore will display the appropriate input control based on the macro that we set on the second parameter

The Type field is the full assembly name of the custom class that we want to use to perform the logic behind this personalization rule

4. Assign our custom element default tag definition to our custom tag


Of course we  can assign our custom element tag definition to one of the existing tag under /sitecore/system/Settings/Rules/Definitions/Tags so that it will automatically appear on the content author personalization rule window however if you want to make it obvious which one is your custom ones then I recommend creating your own custom tag and assign it to that

5. Assign the tag to Conditional Rendering

The last step to make the rule visible for the content author to choose from is to assign our custom tag to one of default Rules Context folder


From the picture we’re setting the tag to the Conditional Rendering rules context which will appear when the user want to personalize a certain component, but you can also some other Rules Context folders such as FXM ones.

After we assign the tag, we can verify that the custom personalization rule is available for the content author to choose from


Here’s the class that’s responsible to evaluate the custom rule condition

The class logic is simple and not doing much for the purposes of the tutorial. In a real world scenario you can make a rule that reads from a custom database, read a configuration file, call an external API (be careful with this as it will increase page load time).

This may sound like a lot of work at first compared to just creating a custom code in the rendering or similar approach. But when we consider that we’re enabling the content author/marketers to do it by themselves and removing/minimizing the dependency towards IT, it would lessen time to market and open up more possibilities for the marketers of what they can do using the platform.


Sitecore built-in security roles

As the title suggested, gathered from the cookbooks

Client Configuration

Sitecore Limited Content Editor

  • Limits features to provide a simplified Content Editor interface.

Sitecore Limited Page Editor

  • Limits features to provide a simplified Page Editor interface.

Sitecore Minimal Page Editor

  • Removes the ribbon from the Page Editor.


  • Provides access rights to the /sitecore/content branch of the content tree.
  • Member of Sitecore Client Authoring.


  • Provides access rights to the areas of the content tree required when making design changes.
  • Member of Sitecore Client Designing.


  • Provides access rights to the areas of the content tree required during site development and maintenance.
  • Member of Author, Designer, Sitecore Client Developing, Sitecore Client Maintaining, and Sitecore Client Configuring.

To eliminate unnecessary features in the user interface and minimize the potential for users to invoke features by mistake, users should be members of the fewest possible roles. The only exception to this rule is the limited and minimal roles described previously; users should be members of these roles whenever possible. Most users should only be members of the Sitecore Client Authoring role. When users require additional functionality, security administrators can give them additional roles.


Client Authoring 

  • Access to the Marketing Center.

Analytics Reporting

  • Access to the Marketing Center, Engagement Plan Monitor and to the Executive Dashboard.
  • Requires membership of the Client Authoring role.

Analytics Maintaining

  • Access to the Marketing Center, Engagement Plan Designer and Supervisor.
  • Requires membership of the Client Authoring role.

Analytics Testing

  • Access to the Test Lab in the Marketing Center as well as access to the test functionality in the Page Editor and in the Content Editor.
  • Requires membership of the Client Authoring role.
  • Members of this role can create and edit test variations.
  • Users who are not members of this role can switch test variations.
  • Members of the Minimal Page Editor role cannot switch test variations.

Analytics Personalization

  • Access to the personalization functionality in the Page Editor and in the Content Editor.
  • Requires membership of the Client Authoring role.
  • Members of this role can create and edit personalization rules.
  • Users who are not members of this role can switch personalization variations.
  • Members of the Minimal Page Editor role cannot switch personalization variations.

Analytics Content Profiling

  • Access to the content profiling functionality in the Page Editor and in the Content Editor.
  • Requires membership of the Client Authoring role.

All of the analytics roles are members of the Client Users security role


Sitecore Client Form Author

  • The Sitecore Client Form Author role gives the user access to the minimum features of the Web Forms for Marketers module. All the other roles expand the user’s access rights. This role allows the user to:
    • Insert a new form.
    • Edit an existing form.
    • View the Summary report

Sitecore Client Developing

  • The Sitecore Client Developing role allows the user to use the Export to ASCX button in the Form

Analytics Maintaining

  • Use the Analytics page in the Create a New Form wizard
  • Use the Analytics section on the Form Designer ribbon
  • Use the Analytics section on the Content Editor ribbon
  • Use tags

Analytics Reporting

  • View the Dropout report.
  • View the Usability report.
  • View the Save Failures report

Sitecore Marketer Form Author

  • The Sitecore Marketer Form Author role inherits access rights from the following roles:
    • Sitecore Client Form Author
    • Analytics Maintaining
    • Analytics Reporting

Sitecore Client Securing

  • The Sitecore Client Securing role allows the user to:
    • Edit the Create User save action.
    • Edit the Edit Role Membership save action.
    • Edit the Change Password save action

Using powershell to install Sitecore from a zip file until we get a running website

I had a chance to play around with powershell to get Sitecore up and running supplied only with the Sitecore zip file. Starting with a discussion with a colleague of mine about how powershell can register a website in IIS and also have access to Sql Server database i’m curious to actually try it out.

The script basically does the following

  • Get Sitecore CMS and DMS zip file from a specified folder file
  • Extract both zip file into a target folder
  • Structure the folder so that DMS files goes into the right folder
  • Register a new web application pool in IIS
  • Register a new website in IIS
  • Update the host file
  • Attach the database files in Sql Server
  • Start the website
  • Open a browser and if all went ok we’ll have Sitecore displayed

I get to know a few things about powershell as well in doing this, it’s actually pretty powerfull stuff. Feel free to checkout the code in

Sitecore Content Tree Structure

I’m sure there are a lot of variation implementing content tree structure out there, here I’m sharing the content tree structure that i have grown liking to.

The idea is to keep things simple and organized for the content editor so they can work their way around the site and feels natural about how the content is structured.



We start simple, a website node has two child node, a home page node and a libraries node.

A home page node serve as the landing page when the site URL is accessed,  a libraries serve as a place to put the data sources of components that’s being used through out the site.


And there’s pretty much how content tree is structured, as a convention i usually use lowercase and no whitespace for the pages node item name because that translate directly into a URL, so you want a friendly URL to be generated. You can enforce this by using a custom pipeline that change the item name after creation and update but convention is good enough for me.

For the pages under supplementary  pages, these are the pages that do not belong to the site’s pages hierarchy/sitemap and usually i give them alias so we can achieve URL such as /404 instead of /supplementary-pages/404. It’s just a matter of taste but think about it.

Hey, what about multisite ?


What about it ?, we replicate the same structure for the other sites and if you notice we have a global node over there. The global node serve as a place to put shared content across the sites, maybe the sites shared the same banner data source or carousel put it in the libraries of the global node. And that also goes for the shared pages, you can put it in the supplementary-pages of the global node.

The same structure can be found on other places as well



also keep in mind these following things:

  • if you have a need of referencing items avoid referencing by item path and use item id instead because item path can change, for example when the content editor move the item around or rename them.
  • remember that it’s a bad practice to have hundreds of child nodes under a single node, use categorization to manage them – see news page above.
  • if there’s a need to store a huge amount of data that results in hundreds of child nodes don’t try to store it Sitecore as is, give it a thought and see if storing in a custom table suit your requirement better or take a look at the Sitecore Item Bucket.
  • use branch template to specify a content structure.
  • use insert options to specify child node type that can be inserted under a node.
  • use icon to give visual information to your content editor, this way they can easily distinguish which is which, but be wise in the implementation don’t just give any random icon.

Sitecore–update existing file based media to database storage

If you implement a separate server for Content Management Server (CM) and the Content Delivery Server (CD), it is advised that you disable the file based media storage so that CD can retrieve the image information.

The following code shows how to update the existing file based media to database storage, from it you could create a Sitecore app to make a handy tool to update your existing media files.


Sitecore scheduled task util

Often enough we build a functionality in Sitecore by utilizing the Sitecore task scheduler, something like, send an email when this user hasn’t updated x in y number of days.

With the sitecore task scheduler i’ve been struggling to test the functionality, because in Sitecore i cannot trigger the scheduled tasks manually. So what i did was set the schedule as low as 1 sec interval and then just wait until the the process hit my breakpoint.

Luckily i’ve found this little gem of tool, the “Scheduled tasks utils”. This tools will list available task in your database and there’s a little button to execute the task. just what i need!


Sitecore Image Parameters

Found a very strange behaviour with Sitecore image control,  take the following code

i would expect that would render the img tag with the correct height and width, but instead it renders out this

it overrides the height and width that i set and take the image height and width.. odd indeed

luckily we have a way to overcome this without having to use custom control or having to resort to image control – we would like the support the page editor functionality.

Set the parameters explicitly

That’s right,  we need to set the parameters explicitly so that it renders out the correct value.

First, remove the Height and Width attribute from the markup

then in the code behind

and here’s the result

Just like what i wanted.

If you’re wondering what other parameters are supported by the image control, you could find that in the Sitecore SDN

Integrating YAF with Sitecore

In one of my projects, there’s a requirement to integrate a forum into the site that we develop using Sitecore. This forum will be used by the member of the site to as a way to communicate and have discussion among members.

After looking around it seems my options are either use Telligent Community forum or Yet Another Forum .Net (YAF). So I look into each forum to see which one fit the requirement, after a couple of minutes browsing their sites it seems YAF is the best option for us. While Telligen Community offers more seamless integration with Sitecore the fact that the client requirement for the forum is quite simple and YAF is an open source project it was more appealing to me.

So I start looking into integrating YAF with Sitecore, I start searching for articles and clues to how I actually can do this. Google is my best friend in this. After few keywords and a couple of sites that I visited it seems there are two options that I can take to integrate YAF.

The first would be the easiest, which is to install YAF as a stand alone application and wrap it up in an iframe. With this approach it would be cleaner and simpler to implement as we can easily upgrade YAF if we need to because we don’t have to change anything in YAF and the fact that it’s separated from our main app. The details on implementing this can be found here.

The second one would be to change the YAF code, and make it use the Sitecore membership provider. I decided to go with this path, because in the first option because it’s a standalone application and does not integrate the membership provider. Both side has their own users and roles, every time a user login to my main site and tries to access YAF, it would duplicate the user in YAF membership table. it feels like a hack to me and would cause a headache to keep both membership tables in sync.

Luckily I don’t have to do this from scratch, Brian Pedersen has managed to do this using older version of Sitecore and YAF. He was using Sitecore 6.0.1 rev. 090212 but any Sitecore version 6 will do, and YAF 1.9.3. Now unfortunately since I’m using YAF I need to move any changes done by Brian to the latest version of YAF. That’s the easy part, soon as I successfully compiled the changes Brian’s done on YAF 1.9.3 to YAF, I was excited to try it out.

“Unable to find guest user” is the error message that I have to keep figure out for many hours. I dig through the store procedure to figure out what it’s trying to do, I dig through the forum posts looking for clues. And finally I found the answer, every user in YAF should be assigned to “Registered” role to enable them access to the forum. so what I did was login to admin pages, and assign “Registered” role to existing users and it works!.

Now for new users though, this is the bit of code that I use.

I didn’t get very far on implementing this though, but now that the existing user and new users can login to the site and start using the forum is a good sign for me so far. But I would expect some minor issue later on, I’ll deal with it then.

Installing Sitecore DMS

I’m using Sitecore 6.5 and DMS 2.0.0 rev. 110818

Extract the zip file



Open your sql server management studio and attach the database, i named it Sitecore.Analytics.Local


In your Sitecore installation folder, find the ConnectionsStrings.config file –can be found under App_Config folder- and add in the connection string for analytics


Put the analytics config files in App_ConfigIncludes folder


Test it, open Sitecore dashboard and try to open the marketing center


If this page comes up you’re good to go


Change context device based on user agent with Sitecore Rule Engine

I pick this up from one of the John West blog post, i want to able to change the Sitecore context device based on the user agent that it detected, so if the device that access my application is a mobile devices then give them the mobile view, if not give them the standard view.

What we’re going to use here are the Sitecore Rule Engine, so we define a certain rule which trigger an action when the condition is fulfilled.In John’s blog he explained that this can be achieved by creating global rules where the rule set the context device if condition is met, or by running rules that is associated with each device.In this post i’m only interested in the global rule approach.

First add this code in the web.config

note: my assembly is Sitecore.RoyalBorough.SharedSource, if you use something else, you need to replace that

Which is used to register the RulesEngineDeviceResolver class below


We need to create a new template for our rule, so in /sitecore/Templates/User Defined/Rules create a new template called SetContextDeviceRule


which has the following structure


Notice that we set the source for “Rule” to /sitecore/System/Settings/Rules/ Then in Sitecore Content Editor create new folder called Determine Context Device under /sitecore/System/Settings/Rules


The rule that we are going to defined works by specifying a condition, and if the condition is passed then run a certain action(s), so under that new folder create folders called Actions,Conditions, and Rules


Next we need to configure the insert options for those folders, do the following :

  • Set the Actions folder insert options to templates/system/rules/Actionsitecore_contextdevice_insertoptions_setaction
  • Do the same for Conditions folder, but instead pointing to Action template point it to Condition Template
  • For the Rules folder, point it to templates/User Defined/Rules/SetContextDeviceRule

Now that we have configured the insert options for those folders, it’s time to add some item to it. Start by adding a new condition under Conditions folder and call it User Agent Is Mobile


Next set the Text and Type field


Note that the Type field refers to UserAgentIsMobile class in Sitecore.RoyalBorough.SharedSource assembly, which is responsible to figure out if the accessing device is a mobile device or not based on the incoming user agent, code below


Next we need to setup the Action, create a new action under the Actions folder and call it “Set Context Device to This Device”


It refer to SetContextDeviceToSpecificDevice class which will be triggered when the condition is true, this class is responsible to change the sitecore context device, code below

Now we need to setup the rule, under the Rules folder create a new item and call it “Set Context Device To Mobile for Mobile Devices”


That’s it, make sure the assembly –for me it’s Sitecore.RoyalBorough.SharedSource.dll-  is in the sitecore bin folder, and you can start test it right away. If all goes well, you should see different view rendered when you access the site through Mobile devices and from PC

update Jan 17, 2012

If we’re to use Sitecore 6.1, we have a problem when we try to change the context device, the layout does not get updated it’s still uses the old layout and not the mobile layout, as a result when the mobile device access our page the rendered layout is all messed up. This is fixed on Sitecore 6.4, for 6.1 here’s the workaround

Create a new LayoutResolver class

Edit the web.config and replace Sitecore LayoutResolver with our own

Now things should work as expected in Sitecore 6.1