Blog posts by Dmytro Duk

Planned maintenance of Visitor Intelligence data storage in East US

Fri, 07 Aug 2020 14:06:58 GMT

Data storage used by Visitor Intelligence and Profile Store in East US requires maintenance to enable Microsoft to migrate resources to newer hardware in Azure.

The maintenance is planned on Monday, August 10, 02:00-04:00 AM Eastern Time Zone, when the traffic is minimal in East US. This maintenance will not affect any other regions.

While most product updates and changes cause no services interruption, this update may result in a delay in event processing during the update. The product will catch up with event processing after the update is completed and events tracked during the update should not be lost. Please try to minimize using Profile Store REST API during the maintenance, please avoid updating data.

We apologize for any impact that this maintenance may have. The team works hard to minimize the impact of this maintenance, and to provide our customers with as much information as possible.

A sneak peek of segmenting based on historical data in Episerver Insight

Thu, 12 Sep 2019 01:00:39 GMT

Yes, we are going to enable segmenting based on historical data. See below how you can do it soon. Today: Segments based on profiles Insight users have 2 options for creating segment based on profiles data: using filter in Insight UI and defining OData-like queries using Profile Store API. Please find more information about managing

A sneak peek of segmenting based on historical data in Episerver Insight

Wed, 11 Sep 2019 23:00:39 GMT

Segments in Profile Store and Insight

Tue, 16 Oct 2018 13:47:00 GMT

This blogpost introduces segments and describes how segments can be managed using Profile Store API and Insight. Using segments in CMS personalization and in Intelligent Campaign is outlined.

What is segment

A segment is a dynamic collection of visitor profiles that match certain criteria. Defining a segment is defining conditions or filters that profiles should match. Simple segment example: users who came to a website today.

Segments are dynamic

Please note that example segment above is dynamic. Probably it is a different group of users every day. Some users might be the part of this segment yesterday, but today they do not match the segment if they have not visited the website. Returning visitors will still be the part of this segment tomorrow.

Segments are based on profiles

Segments are based on profile data and filters/conditions can be defined for profile properties. Currently (version 1.6.0) it is not possible to define a segment based on tracking events. Visitor statistics should be aggregated and stored in the visitor profile to be used when matching segment rules.

Managing Segments

There are 2 ways to manage segments (and 2 target user groups):

Using Insight UI (marketers)
Using Profile Store API (developers)

Most of segment operations are available using both options, however there are some differences described below.

Creating segments

Creating Segments in Insight UI

Marketer can filter profiles by Contact information, Last Seen date and Country facets in Profiles section of Insight UI. Entering a query in the search box performs the search based on visitor name and on profile Info collection that may contains email address, company name etc.

Selected filters in Insight UI can be saved as a segment. Insight suggests proper segment name based on the current set of filters and allows making the new segment available in visitor groups. Current user name is stored in the SegmentManager field.

Creating segments in the Insight is limited by available UI facets. Selected combination of filters is stored as JSON in ProfileFilter segment property.

Please note that in current version 1.6.0 segments created in Insight UI are not tied to specific scope and can be used to slice profiles in all scopes.

Creating Segments in Profile Store API

Segment can be created by POST request to /segments endpoint of Profile Store API. Segment JSON data is passed in the request body.

Note: filter to match profiles is defined in ProfileQuery property (unlike segments created in Insight UI that store filters in the ProfileFilter segment property).

The syntax for ProfileQuery is described in Filtering, paging, and sorting article and in Microsoft Rest API Guidelines.

POST api/v1.0/segments
{
    "Name": "Episerver Employees",
    "Scope": "default",
    "ProfileQuery": "Info.Company eq Episerver",
    "AvailableForPersonalization": true
}

Name, Scope and ProfileQuery values are required.

The new created segment data is returned in the 201 Created response body:

{
  "SegmentId": "912f2150-82b5-5fa7-88c4-2d42fa700ac8",
  "Scope": "default",
  "SegmentManager": null,
  "ProfileQuery": "Info.Company eq Episerver",
  "AvailableForPersonalization": true,
  "Archived": false,
  "FavoredBy": [],
  "Name": "Episerver Employees",
  "CreatedDate": "2018-10-12T16:16:25.2186793Z",
  "ModifiedDate": "2018-10-12T17:22:11.3000335Z",
  "MatchingProfiles": 4
}

Please note that any segment created using Profile Store API is always scoped and can be used to match profiles in the corresponding scope.

The main advantage of creating segment using API is that developer is not limited by available filters in the Insight UI. ProfileQuery is defined in the same way as filter when querying profiles and can include conditions for several properties in the profile data model, including information in the dynamic Payload object.

It enables developers to aggregate values specific to customer business, store it in profile payload and create custom segments based on custom data.

/segments endpoint returns 400 Bad Request or 500 Server Error if provided segment definition is invalid or error happens when creating a segment.

Loading Segment Data

Viewing Segment in Insight UI

Segments are listed in the Segments section of Insight UI. Marketer uses simple filtering to view segments managed by current user, recently created, favorited, archived or all segments.

Clicking on the segment opens segments details and the list of profiles that currently match this segment.

Querying segments in Profile Store API

Developers can query existing segments by GET request to /segments endpoint of Profile Store API. Basic filtering, paging and sorting is supported according to the Microsoft Rest API Guidelines.

$filter querystring parameter is used to define a filtering expression that will be evaluated for segments. The following logical operators are supported within $filter expression: eq, ne, gt, ge, lt, le, and, or, not.

Please see Microsoft Rest API Guidelines and Filtering, paging, and sorting article for more examples and details about querying profiles, events and segments in Profile Store API.

For example, the following should request 2 latest segments defined in the default scope by specific user:

GET api/v1.0/segments?$filter=Scope eq default and SegmentManager eq marketer@example.com&$orderBy=CreatedDate DESC&$top=2

The returned result 200 Ok contains the collection of segments that match defined filter, the number of returned items based on $top value and the total number of matching segments (first segment is created using API and the second is created in Insight UI):

{
  "items": [
    {
      "SegmentId": "912f2150-82b5-5fa7-88c4-2d42fa700ac8",
      "Scope": "default",
      "SegmentManager": "marketer@example.com",
      "ProfileQuery": "Info.Company eq Episerver",
      "AvailableForPersonalization": true,
      "Archived": false,
      "FavoredBy": [],
      "Name": "Episerver Employees",
      "CreatedDate": "2018-10-14T21:16:25.2186793Z",
      "ModifiedDate": "2018-10-14T21:22:11.3000335Z",
      "MatchingProfiles": 4
    },  
    {
      "SegmentId": "1e2987f2-3285-4b72-83b8-1b50b1e29613",
      "Scope": "default",
      "SegmentManager": "marketer@example.com",
      "ProfileFilter": {
        "Rules": [
          {
            "Text": {
              "Field": "Country",
              "Method": "IsExactly",
              "Value": "DE"
            }
          },
          {
            "And": {}
          },
          {
            "Text": {
              "Field": "ContactInformation",
              "Method": "IsExactly",
              "Value": "Known"
            }
          },
          {
            "And": {}
          },
          {
            "Date": {
              "Field": "LastSeen",
              "Method": "Within",
              "Values": [
                "OneWeek"
              ]
            }
          }
        ]
      },
      "AvailableForPersonalization": true,
      "Archived": false,
      "FavoredBy": [],
      "Name": "Identified from Germany last seen within 1 week",
      "Description": null,
      "CreatedDate": "2018-09-28T15:01:54.6417241Z",
      "ModifiedDate": "2018-09-28T15:01:54.6417241Z",
      "MatchingProfiles": 15
    }
  ],
  "total": 5,
  "count": 2
}

Please note that the number of matching profiles returned for each segment in the list is not re-calculated. MatchingProfiles property value is the number of patching profiles at the moment when the segment was created or updated last time.

In case of error or invalid request the error message and code 500 or 400 are returned. For example, invalid filter syntax:

GET /api/v1.0/Segments?$filter=SegmentManager == test@example.com

400 Bad Request response is returned:

{
  "error": {
    "code": "400",
    "message": "Invalid comparison phrase \"SegmentManager == test@example.com\"",
    "target": "",
    "details": []
  }
}

Getting segment data in Profile Store API

Specific segment data can be loaded by specifying the segment ID:

GET api/v1.0/segments/912f2150-82b5-5fa7-88c4-2d42fa700ac8

MatchingProfiles property value is re-evaluated when loading single segment data, it is the current number of matching profiles now:

{
  "SegmentId": "912f2150-82b5-5fa7-88c4-2d42fa700ac8",
  "Scope": "default",
  "SegmentManager": "marketer@example.com",
  "ProfileQuery": "Info.Company eq Episerver",
  "AvailableForPersonalization": true,
  "Archived": false,
  "FavoredBy": [],
  "Name": "Episerver Employees",
  "CreatedDate": "2018-10-12T16:16:25.2186793Z",
  "ModifiedDate": "2018-10-12T17:22:11.3000335Z",
  "MatchingProfiles": 183
}

Updating Segments

Editing in Insight UI

Segment editing is partially supported in Insight UI. Editing menu is available by clicking on corresponding icon in segment list and in segment details view.

Inline editing is enabled for segment name and description when viewing segment details.

Currently changing the segment filters to match profiles is not supported in the Insight UI.

Updating in Profile Store API

Existing segment can be completely replaced/overridden by PUT request to /segments endpoint and specifying the segment ID. For example, here we put a new segment data that includes description:

PUT api/v1.0/segments/912f2150-82b5-5fa7-88c4-2d42fa700ac8
{
    "Name": "Episerver Employees",
    "Description": "All profiles that have Episerver value in Info.Company property",
    "Scope": "default",
    "ProfileQuery": "Info.Company eq Episerver",
    "AvailableForPersonalization": true,
    "SegmentManager": "marketer@example.com"
}

PUT request creates a new segment if there is no existing segment with specified ID.

Like POST method, the response body contains new segment data.

Please note that updating/replacing segments that were created in the Insight UI is not supported in the Profile Store API. Technically it means that a segment cannot be updated using Profile Store API if segment ProfileFilter property is not null.

Removing Segments

Deleting segments is not supported in the current versions (1.6.0) of both Insight UI and Profile Store API. The main reason is that removing a segment may cause problems if deleted segment is used anywhere in the application, for example in visitor groups or any other integration. Removing segments may be implemented later.

Archiving Segments

Archiving is a way to hide segments that are not actively used in Insight UI. These segments can be found in Archived section of Segments view.

Using Segment

Personalization Using Segments

NuGet package Episerver.Insight.Cms provides the Insight segment visitor group criterion. Insight API base URL and subscription key must be defined in appsettings episerver:profiles.InsightApiBaseUrl and episerver:profiles.InsightApiSubscriptionKey.

After installing the package and updating configuration, Insight segment criterion can be used when creating a visitor group. The list contains existing segments that have property value AvailableForPersonalization=true (available in visitor group in Insight UI).

Selecting a segment means that visitor should be the part of visitor group if his/her profile matches segment (fits the segment filters).

Archived segments cannot be selected when creating a new visitor group, however it still works for personalization if it was selected in the visitor group criterion before archiving the segment.

For example, marketer filters profiles by Country, creates a segment of visitors from Germany, adds Insight criterion in the visitor group settings and select this segment. Now this visitor group can be used to personalize content, for example to invite visitors from Germany to subscribe to newsletters for German clients.

Segment in Intelligent Campaign

Intelligent Campaign is another good example of using segments. When creating a campaign, marketer can add the Insight Segment node in the working area and select a segment that should be used to filter recipients when sending campaign message.

Using segments in Campaign enables dynamic recipient targeting based on profiles information.

Implement your own integration!

I hope that developers will build new products and integrations on top of Profile Store. I’m looking forward to see your custom segments, personalization, visitor classification, activity analysis, integrations with CRM/ERP/whatever systems, websites and offline stores. Your feedback is very welcome!

User interface improvements in EPiServer Find 9.5

Thu, 30 Jul 2015 13:11:00 GMT

EPiServer Find 9.5 brings the number of bug fixes and new things. This blog post describes what is new in Find UI.

User interface improvements

The goal was to get rid of multiple scrollbars in Find UI and provide better user experience. In updated UI certain UI elements like grid headers, buttons and sidebars stick to the top or to the bottom of the current view when user is scrolling.

The following screenshots show what has been changed in Find 9.5 UI. Click to see the whole picture.

Statistics / Most frequent searches

Statistics / Searches without hits, Searches without relevant hits

Optimization / Best Bets, Related Queries, Synonyms, Autocomplete

Overview

Explore

Feedback

Let us know how it feels!

Disqus for EPiServer 8

Fri, 06 Mar 2015 00:24:00 GMT

Disqus for EPiServer 8 is available.

What's new

Disqus comments 1.2.0 add-ons are compatible with EPiServer CMS 8.
Packages can be installed from Visual Studio. Also add-ons are available in the Add-on Store (Third Party section).

System requirements

EPiServer CMS 8 and later version.

MVC and WebForms sites are supported.

Installing add-ons from Visual Studio

Starting from this version, Disqus for EPiServer packages can be installed from Visual Studio.

Make sure http://nuget.episerver.com/feed/packages.svc/ is added as a NuGet source and episerver.packaging@installationMode is set to Code in web.config. See details in developer guide.

You can find packages by searching for "disqus".

Add-ons are installed under /modules site directory. Disqus comments configuration UI add-on is deployed under /modules/_protected sub-folder since it is protected add-on and should be accessed only by the authorized users within WebEditors or WebAdmins roles by default.

Upgrading Disqus add-ons to version 1.2.0

First of all, upgrade website to EPiServer 8.

Upgrading add-ons from Visual Studio

Make sure installationMode is set to Code: <episerver.packaging installationMode="Code">
If the installationMode was set to UI you need to run the cmdlet Convert-EPiAddons in the Package Manager Console, it will convert any existing add-ons installed via UI to Visual Studio format.
Remove Duk.EPiServer.Disqus.* assemblies in /bin and /modulesbin directories. Remove /modules/Duk.EPiServer.Disqus and /modules/_protected/Duk.EPiServer.Disqus.UI folders.
Make sure http://nuget.episerver.com/feed/packages.svc/ is added as a NuGet source in Visual Studio.
Install Disqus comments 1.2.0 packages via Visual Studio. Overwrite all existing files in Disqus add-on folders if asked.

Upgrading add-ons from the user interface

Make sure installationMode is set to UI: <episerver.packaging installationMode="UI">
To install add-on packages, the user needs to be a member of the PackagingAdmins user group, and must have access to the EPiServer UI.
Navigate to Add-ons in global navigation menu and update Disqus comments add-ons in Updates section.

More information

Please refer documentation on the project page.

Source code is available on GitHub. Feel free to report issues, ask questions and share any feedback.

Customizing how statistics tracking scripts are loaded on pages when using EPiServer Find

Wed, 11 Feb 2015 20:23:16 GMT

Find injects 2 scripts on site pages in order to track search statistics. By default these scripts are requested from EPiServer CDN. In certain scenarios developer may need to tweak how tracking scripts are added on pages.

Prerequisites

EPiServer Find 8.10.x.x or later version packages should be installed on website.

Loading Find tracking scripts on Intranet websites

Customers may use EPiServer Find on Internal websites where site visitors don’t have access to the Internet, so tracking scripts cannot be loaded from CDN.

Possible solution can be hosting these tracking scripts in customer’s Intranet instead of loading scripts from CDN.

Hosting statistics tracking scripts in Intranet

Download the following scripts from EPiServer CDN. Version 8.10.0 is an example, grab scripts that correspond to EPiServer Find version installed on the website:

https://dl.episerver.net/8.10.0/epi-util/native.history.js
https://dl.episerver.net/8.10.0/epi-util/find.js

Remember to upgrade these scripts when upgrading EPiServer Find on website.

Overriding tracking script locations

Tell Find that scripts should be loaded form Intranet. Script locations can be overridden by defining client resources with corresponding names:

history.js script must be defined as "browserstate.history"
find.js script must be defined as "epi.find.trackingScript"

Specifying script URLs in module.config

The easiest way to define client resource is adding them in site module.config:

<?xml version="1.0" encoding="utf-8"?>
<module>
    ...
    <clientResources>
        ...
        <add name="browserstate.history" path="http://intranet/Scripts/native.history.js" resourceType="Script"/>
        <add name="epi.find.trackingScript" path="http://intranet/Scripts/find.js" resourceType="Script">
            <dependencies>
                <add name="browserstate.history" />
            </dependencies>
        </add>        
    </clientResources>
    ...
</module>

Script path value can be the path on the site or full URL.

Note that browserstate.history is defined as dependency for epi.find.trackingScript to ensure correct order of loading.

Implementing client resource provider in order to define script locations

Another way to define client resources is implementing client resource provider. This options can be useful if script URLs should be somehow resolved in code:

[ClientResourceProvider]
public class ClientResourceProvider : IClientResourceProvider
{
    public IEnumerable<ClientResource> GetClientResources()
    {
        return new[] 
        {
            new ClientResource
            {
                Name = "browserstate.history",
                Path = GetIntranetUrl() + "native.history.js",
                ResourceType = ClientResourceType.Script
            },
            new ClientResource
            {
                Name = "epi.find.trackingScript",
                Path = GetIntranetUrl() + "find.js",
                ResourceType = ClientResourceType.Script,
                Dependencies = new List<string> { "browserstate.history" }
            }
        };
    }
}

Loading Find tracking scripts when history.js is added in page templates

Another scenario could be running EPiServer Find on a website where history.js variation like jquery.history.js script is used in page templates. In this case injecting native.history.js script from EPiServer CDN gives error like "History.js Adapter has already been loaded".

In order to solve this issue, history.js script that is used on website can be defined as a client resource and Find will inject this script instead of requesting native.history.js on CDN.

Defining history.js client resource

history.js script must be defined as "browserstate.history" client resource.

Specifying history.js URLs in module.config

Client resource can be defined in site module.config:

<?xml version="1.0" encoding="utf-8"?>
<module>
    ...
    <clientResources>
        ...
        <add name="browserstate.history" path="PathToMyScripts/jquery.history.js" resourceType="Script"/>
    </clientResources>
    ...
</module>

Where value is the path or full URL of history.js that is used on the site.

Defining history.js path in client resource provider

Another option is defining browserstate.history script in a client resource provider. Make sure that script name is defined as "browserstate.history".

[ClientResourceProvider]
public class ClientResourceProvider : IClientResourceProvider
{
    public IEnumerable<ClientResource> GetClientResources()
    {
        return new[] 
        {
            new ClientResource
            {
                Name = "browserstate.history",
                Path = "ClientResources/Scripts/jquery.history.js",
                ResourceType = ClientResourceType.Script
            }
        };
    }
}

Again, this options can be useful if URL of history.js should be resolved in code.

What if you don’t want to load history.js using client resources framework

Probably there are some cases when loading history.js using client resources framework is not desirable. For example, history.js is bundled with other site scripts and you don’t want to load history.js separately. There is a workaround.

Define fake "browserstate.history" client resource with empty inline content:

[ClientResourceProvider]
public class ClientResourceProvider : IClientResourceProvider
{
    public IEnumerable<ClientResource> GetClientResources()
    {
        return new[] 
        {
            new ClientResource
            {
                Name = "browserstate.history",
                InlineContent = "",
                ResourceType = ClientResourceType.Script
            }
        };
    }
}

Now add your own history.js on pages as you want, but make sure that it is loaded before find.js script (by default required scripts, including find.js, are rendered in the bottom of the page, using something like @Html.RequiredClientResources("Footer")).

Disqus for EPiServer 7.5+

Tue, 23 Dec 2014 18:33:03 GMT

Disqus for EPiServer 1.1 is available in the official EPiServer Add-on Store.

This add-on enables Disqus comments on web sites based on EPiServer CMS 7.5 and later versions.

Go to Third-Party Add-ons section on your site, install Disqus add-ons, set your shortname and start adding comments on your site pages!

This release is just a rebuild for current EPiServer platform, it includes number of minor fixes for Edit and Preview modes and doesn’t contain new features.

System requirements

EPiServer CMS 7.5 and later versions. Technically add-on is rebuild with EPiServer packages 7.6.2 and smoke tested with EPiServer 7.5.394.2 (first released 7.5 version) and EPiServer 7.19.1 (latest update available on December 23 2014).

MVC and WebForms sites are supported.

More information

Please refer documentation on the project page.

Source code is available on GitHub. Feel free to report issues, ask questions and share any feedback.

What’s next

The plan is to release new version that will provide a better support of EPiServer Commerce and make it possible to install Disqus add-on as a NuGet package in Visual Studio. Hopefully in Q1, definitely in 2015. Stay tuned.

Happy Holidays!

Statistics tracking in EPiServer Find

Mon, 09 Jun 2014 16:04:00 GMT

This blog post provides brief overview of statistics available in EPiServer Find and describes how the statistics tracking can be enabled on a website.

Statistics and optimization

Knowledge is power. With EPiServer Find you can track and analyze search activities on your website in order to optimize search results and website content. Statistics views provide the following information:

	Most frequent searches Most frequent searches shows what people are searching on your website the most.
	Searches without hits This is the list of most popular searches that did not result in any hit. Most probably, you want this section to be empty.
	Searches without relevant hits This is new feature. Here you can see more behavioral information: search phrases that had some hits, but these results were not clicked by users, which probably means that these hits were not so relevant for visitors.

All statistics views display up to 100 top search phrases.

Using statistics you can start optimizing search experience. Depending on specific case, you can combine the following techniques:

Create best bets to promote certain content and make sure that it is on top of results
Suggest phrases that can be related to current user search, kind of did-you-mean hints
Define synonyms for related phrases in order to provide more relevant hits
Optimize your content and structure to make sure that you have what they need and it’s easy to find
Blame users who searches for ' kammy koopa' and 'boom boom' on your corporate website. No, you cannot do anything with these guys. At least using Find. So far.

Please see user guide for more information about statistics and optimization in new EPiServer Find.

Enabling statistics tracking

Just add Track() method in a query chain:

var hits = searchClient.UnifiedSearchFor("unicorn")
        .Track() // track them all!
        .GetResult();

Rendering search hits

When tracking is enabled, search hit URLs contain additional parameters like search query, site and language, client IP address and hit position.

Output hit URLs as is when rendering search results:

<a href="@hit.Url">@Html.Raw(@hit.Title)</a>

When user clicks on search result, parameters are extracted from hit URL, stored in a cookie and browser navigates to the clean hit URL. It works also for search hits of external content indexed by crawler, while user just (left-)clicks or taps external hit link on a search page.

Information about the click is reported to the backend as soon as CMS page is loaded next time. For CMS content, the “next time” is immediately when clicked page is opened.

Statistics is also collected when the link to CMS content is opened in a new tab by Ctrl+click or using right-click menu or when the hit URL is being copied (sent to other user, maybe) and opened in a new browser window, except of links to external resources.

To make it happen, Find injects JavaScript resources on pages. Your templates should meet the standard requirements for EPiServer CMS page templates:

Client resource registers must be executed before rendering the page. The easiest way is to inherit one of the base page classes.
Page templates must render required client resources for the Header and Footer default areas. Use RequiredClientResources control for Web Forms or RequiredClientResources MVC helper:

Rendering required client resources in the page header in Web Forms:

<head>
    ...
    <EPiServer:RequiredClientResources RenderingArea="Header" 
        ID="RequiredResourcesHeader" runat="server" />
</head>

Rendering required client resources in the page footer in MVC:

<body>
    ...
    <%= Html.RequiredClientResources(RenderingTags.Footer)%>
</body>

When tracking is not needed

Sometimes you may not want to track search statistics or you need monitor search activity conditionally. Maybe you don’t want to track statistics when executing searches in order to list content by certain criteria, like listing of latest news or specific products.

Just don’t use Track() method if you don’t need to track.

Tracking script is not injected on pages and statistics is not collected if Do Not Track header is detected.

Use it

Use statistics and optimize, make sure your visitors get what they are looking for!

Disqus for EPiServer

Tue, 18 Jun 2013 10:59:06 GMT

Let me introduce Disqus for EPiServer, a Disqus comments integration for EPiServer-based websites. The module consists of two add-ons which enable discussions on pages and provide user interface for configuration.

Now Disqus for EPiServer add-ons are available in the Third-Party Add-ons section in the official EPiServer Add-on Store.

Enabling Disqus comments

There are several ways to display Disqus comments on pages:

Adding comments as a shared block (target user: editor)
Adding comments as a dynamic content (target user: editor)
Displaying discussions in the rendering areas defined in the templates (target user: developer)
Rendering comments block as a content property (target user: geeky developer)

Configuration UI and Edit mode extensions

Configuration user interface allows to edit Disqus settings for the current website and provides quick links to moderation tools in Disqus Admin.

Edit UI extensions help to work with Disqus blocks when editing a content. Warnings are displayed when Disqus configuration is not complete or there are problematic blocks on the current page. These indicators are not rendered in view mode.

Basic installation scenario

Signup on Disqus and choose a shortname for the site
Install Disqus for EPiServer add-ons
Set shortname and enable discussions on website using Disqus configuration UI.
Start adding Disqus comments on pages.

System requirements

EPiServer 7.x.x CMS, Add-on system (EPiServer.Packaging). EPiServer UI Platform (Shell) is required to install configuration UI and Edit mode extensions.

MVC and WebForms sites are supported. EPiServer 7 Patch 3 is required on MVC sites.

More information

Please refer documentation on the project page.

Source code and feedback

Source code is available on GitHub.

Feel free to report bugs, ask questions and request features on GitHub or here in comments. Your feedback is highly appreciated.

Dependencies and versioning for EPiServer add-ons

Thu, 28 Mar 2013 19:17:00 GMT

One of the most challenging problems that the Add-on system should solve is handling a lot of dependencies between different products.

Site owners want to be sure that installed add-ons are compatible with the current environment. Add-on authors (developers, partners and EPiServer) want to release new product versions and make the upgrade easy for customers.

This blog post describes how the EPiServer Add-on system handles dependencies and prerequisites and provides general rules and recommendations to consider when defining dependencies and versions for add-ons.

Problem: Dependency hell

The following quote is a great description of the problem:

In systems with many dependencies, releasing new package versions can quickly become a nightmare. If the dependency specifications are too tight, you are in danger of version lock (the inability to upgrade a package without having to release new versions of every dependent package). If dependencies are specified too loosely, you will inevitably be bitten by version promiscuity (assuming compatibility with more future versions than is reasonable). Dependency hell is where you are when version lock and/or version promiscuity prevent you from easily and safely moving your project forward.

http://semver.org

Solution: Semantic versioning

Semantic versioning is a set of rules to follow when defining version numbers for your component (public API, package, plugin, module, add-on, etc). It was suggested by Tom Preston-Werner. Please have a look at official SemVer website for details.

The general idea is that a version has three parts, Major.Minor.Patch, and each part indicates backward compatibility:

Major: breaking changes. Increasing Major part means that this version has breaking changes and it is not backwards compatible.
Minor: new features. Increasing Minor part means that this versions contains new functionality but it is still backwards compatible.
Patch: bug fixes. Increasing this Patch part means that this version contains bug fixes and is backwards compatible.

A suffix appended to the Patch part and separated by dash symbol indicates prerelease version. Prerelease versions are sorted alphabetically and are always lower than release version with the same Major.Minor.Patch numbers.

Examples:

Module 2.0.0 introduces breaking changes and is not compatible with Module 1.7.0.

Module 1.7.0 is backwards compatible with Module 1.1.3, meaning that other component which depends on Module 1.1.3 should work fine with newer version 1.7.0.

There is no functional differences between Module 1.1.3 and Module 1.1.0 and these components are compatible, however 1.1.3 fixes some bugs.

NuGet supports package versioning according to the Semantic Versioning specification. In general the Add-on system follows NuGet guidelines and patterns.

Defining the add-on version

Recommendations when defining the add-on version

DO:

Use semantic versioning conventions when defining the version. Make sure that the Major part is increased if the new version introduces breaking changes. Increase the Minor part if the new add-on version brings new functionality but possible dependents should still work fine with it. Increase only the Patch part when the new version contains minor improvements and bug fixes.
Use a combination of AssemblyInformationalVersionAttribute and AssemblyVersionAttribute when creating an add-on package from a project.
Increase the Major version number when your add-on is rebuilt and it introduces breaking changes, even if it does not provide any new functionality or bug fixes.

DO NOT:

Avoid increasing the Major version number just because it sounds great or because sales guys ask you.
Do not increase the Major version number depending on your dependency versions. New (Major) version of your add-on should reflect (breaking) changes in your add-on.

The add-on version can be defined in package / metadata / version node in .nuspec file:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    <id>Alloy.Sample</id>
    <version>1.2.3</version>
    <authors>Alloy</authors>
    <description>Sample add-on.</description>
  </metadata>
</package>

You can use special placeholders in .nuspec file if package is created from a project:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    <id>$id$</id>
    <version>$version$</version>
    <authors>$author$</authors>
    <description>$description$</description>
  </metadata>
</package>

In this case add-on version should be set using AssemblyInformationalVersionAttribute or AssemblyVersionAttribute, usually in AssemblyInfo.cs file:

[assembly: AssemblyVersion("1.2.3.0")]
[assembly: AssemblyInformationalVersion("1.2.3")]

Using AssemblyInformationalVersionAttribute allows to set semantic version in form of Major.Minor.Patch, in example above "1.2.3". These 3 numbers will be set in the .nuspec file and used in the package file name: Alloy.Sample.1.2.3.nupkg.

The AssemblyVersionAttribute value is used as an add-on version if AssemblyInformationalVersionAttribute is not found. Please note that in this case you will get 4 numbers in the version and file name (Alloy.Sample.1.2.3.0.nupkg), even if you specify 3 numbers in the attribute value. I would recommend using 0 as the fourth number in the AssemblyVersionAttribute value as in example above since it does not fit the SemVer pattern. You can use AssemblyFileVersionAttribute if you distinguish different revisions as file versions.

Defining prerelease add-on version

Prerelease add-on versions can be defined directly in the .nuspec file or using the AssemblyInformationalVersionAttribute when the package is created from a project:

[assembly: AssemblyInformationalVersion("1.2.3-beta")]

Enabling prerelease versions in Add-On Store

By default prerelease add-on versions cannot be installed and they are not visible in Add-On Store. Set the allowPrereleaseVersions attribute of episerver.packaging element to "true" to enable installing prerelease package versions on the site:

<configuration>
  <!-- ... ommited configuration ...-->
  <episerver.packaging allowPrereleaseVersions="true" ... >
    <packageRepositories> ... </packageRepositories>
  </episerver.packaging>
</configuration>

Defining the add-on dependencies

An add-on has a dependency when it relies on some other module or component that needs to be deployed or installed on the website.

_{Photo: http://www.caryballetconservatory.com}

Before installing any add-on the system tries to find all dependencies and dependents and check if all components are compatible.

Given that component functionality usually differs from version to version and that new major versions usually contain breaking changes, information about dependency usually contains the component identifier and the lowest compatible version number or a version range.

Add-on dependencies should be defined in the .nuspec file as described in the NuGet documentation. The NuGet Versioning article describes the general idea of specifying dependency version ranges.

Try to minimize the number of dependencies and avoid dependencies on third-party components.

The main guideline when defining add-on dependencies is to always set the lowest compatible dependency version. In addition you may want to define version range to set the maximum compatible version if your add-on functionality likely won’t be compatible with next major version of the dependency.

Dependencies on other add-ons

An add-on may rely on another add-on. When this add-on is being installed to the website, its dependency is installed automatically if possible.

For example: add-on A depends on add-on B. Add-on B relies on add-on C. When the user installs add-on A, the system will also install add-ons B and C.

Use the package ID of dependency add-on as the dependency identifier and specify the lowest compatible version or version range.

Example: you have developed a component to extend the Edit UI in and work with EPiServer Commerce data. The component uses some new features released in Edit UI 2.0 and is not compatible with the first version. The Edit UI is also an add-on and its package ID is “CMS” (I agree, not the ideal name for this package. We use this ID for backwards compatibility because in EPiServer 6 we had a protected Shell module "CMS").

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    ...  
    <dependencies>
      <dependency id="CMS" version="2.0" />
    </dependencies>
  </metadata>
</package>

Prerequisites

Prerequisites are used to define required products and ensure platform compatibility.

A prerequisite is a dependency that is not available as an add-on and cannot be installed by the Add-on system. Prerequisites should be deployed on the website before installing the dependent add-on.

All assemblies loaded in the application domain are listed as virtual packages. It allows you to define prerequisites in the same way as dependencies on other add-ons. You just add a package dependency in .nuspec file and use the assembly name (without extension) as the dependency identifier and specify the assembly version or version range.

Let’s define EPiServer 7 Commerce as a prerequisite for the sample add-on described in the previous section. As the dependency identifier use the name of the “main” prerequisite product assembly. EPiServer.Business.Commerce assembly should be a good choice in this case. Set the lowest compatible Commerce version, for example 7.0. Use a version range to define the highest compatible version of EPiServer Commerce.

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    ...  
    <dependencies>
      <dependency id="CMS" version="2.0" />
      <dependency id="EPiServer.Business.Commerce" version="[7.0,8.0)" />
    </dependencies>
  </metadata>
</package>

In this example version range defines all EPiServer Commerce versions 7.x.x as compatible but excludes the next major release 8.0.0.

Dependencies on third-party components

Implicit dependencies

An implicit dependency is a server-side or client-side component that is used by an add-on but which is not defined as a dependency in the add-on .nuspec file explicitly. You create implicit dependencies if you include third-party assemblies or JavaScript frameworks in your add-on package. You may face different kinds of problems if the same components are included in other add-ons. It is impossible to control and make sure that add-ons and components are compatible with each other and with the website environment.

There are several ways to avoid this problem:

Get rid of the additional dependencies. Consider implementing that piece of functionality in your code when it is reasonable.
Define a prerequisite when your dependency is a product or platform that should be preinstalled/deployed to the website.
Consider creating a separate package for each third-party component to make it possible to install these components as an add-on. In this case other developers can reference these components and use them as dependencies for their add-ons. Contact EPiServer to discuss creating dependency packages.

Never include third-party assemblies or client side frameworks in your add-on package.

Dependencies on third-party assemblies and other server-side resources

Several versions of the same assembly should not be loaded in the website AppDomain. That's why it is especially important to make sure that dependencies on third-party assemblies and versions can be handled properly.

Google Analytics for EPiServer 7 and Social Reach add-ons use DotNetOpenAuth library for authentication. We don't include DotNetOpenAuth assemblies to these add-ons. DotNetOpenAuth assembly is included in a separate package that can be referenced as a dependency by any other add-on.

There is no point in installing DotNetOpenAuth as a standalone add-on because this is a framework that is used by other products. You don't see these dependency add-ons in the Add-on Store, but you get DotNetOpenAuth installed as soon as you install Google Analytics or Social Reach add-ons on your website.

Dependencies on third-party JavaScript frameworks and other client resources

The same rules should work for client side components. It would be strange if several add-ons include jQuery framework or define other JavaScript library hosted on CDN as client resources in the module manifest. Including several versions of the same framework on pages may cause conflicts or unexpected behavior and results.

Try to avoid including third-party client-side components and frameworks in your add-on. Consider implementing required functionality in your code. Otherwise consider creating dependency package for each third-party framework that can be used by other modules.

Creating dependency packages

A dependency package should contain only one third-party component. It can be created in the same way as usual add-on packages and it should follow the same rules for versioning. Dependency package can depend on other dependency packages.

The following tags are required in the .nuspec file of the dependency package: EPiServerModulePackage, EPiServerDependency.

Recommendations when defining dependencies

DO:

Always specify the lowest compatible dependency version. Consider setting the highest compatible version to avoid incompatibility with the next major version of the dependency.
Use the add-on package ID when defining a dependency on that add-on.
Use the corresponding assembly name when defining a prerequisite.
Try to avoid extra dependencies when possible.
Define any dependency on a third-party component as an add-on dependency or prerequisite.
Create one dependency package for each third-party component.
Contact EPiServer when you consider creating dependency add-on packages for a third-party component

DO NOT:

Do not include third-party components (server side or client side) in your add-on package.
Do not use the assembly name as the dependency identifier when defining a dependency on another add-on. For example, use add-on ID “CMS” instead of assembly name “EPiServer.Cms.Shell.UI” when you define a dependency on the Edit UI.
Do not list indirect dependencies. The .nuspec file of your add-on should state only direct dependencies on add-ons and components that are used in your add-on.
Avoid circular dependencies.

Feedback

We are trying to define best practices and our recommendations may evolve depending on our needs and experience. That’s why your feedback is (as always) highly appreciated. Let us know about your cases!

More information

EPiServer Framework SDK – Add-ons

NuGet documentation

Semantic version

Sharing Widget for EPiServer 7

Wed, 23 Jan 2013 14:46:00 GMT

Sharing Widget add-on provides easy way to get ShareThis buttons on EPiServer 7 site. Just create new block, specify your publisher ID and drop it on a page. Both Web Forms and MVC are supported.

Please download Sharing Widget add-on package to install using Manual Upload option.

Source code is available on GitHub.

Feedback

Your feedback is highly appreciated. Please let me know if you are interested in further add-on development and which features you would like to see (selecting required buttons, size, other settings?). Don’t hesitate to report bugs and issues or leave a comment here.

Rebuilding the add-on for EPiServer 7

This module was developed as a sample add-on for EPiServer 7 Preview. Now it is time to rebuild it for RTM version. To keep it simple I decided not to introduce any new functionality and concentrate on what should be changed to make it work with EPiServer 7.

Surprisingly, there was not so much to update. You can see most of changes in this commit. Please see details about most important fixes below if you are interested.

Block controller

This is probably the only one required change: the name of block data parameter in Index method is changed from blockData to currentBlock, otherwise current block data is not passed in action method and you get NullReferenceException when rendering content in the view.

public class SharingWidgetBlockController : BlockController<SharingWidgetBlock>
{
    public override ActionResult Index(SharingWidgetBlock currentBlock)
    {
        // Hint for MVC to find the view in modules folder:
        return PartialView(Paths.ToResource(GetType(), "Views/SharingWidget/SharingWidget.cshtml"), currentBlock);
    }
}

That was not so obvious, huh?

Translation for content type and property names and descriptions

Embedded language file for English is added. Titles and descriptions for Sharing Widget block type and properties are defined in /language/blocktypes/blocktype and /language/pagetypes/common/property nodes.

<?xml version="1.0" encoding="utf-8" ?>
<languages>
  <language name="English" id="en">
    <blocktypes>
      <!-- Blocks -->
      <blocktype name="SharingWidgetBlock">
        <name>Sharing Widget</name>
        <description>Adds ShareThis widget on pages where block is placed.</description>
      </blocktype>
    </blocktypes>
    <pagetypes>
      <common>
        <!-- Sharing block properties -->
        <property name="PublisherId">
          <caption>Publisher ID</caption>
          <help>Register on ShareThis.com to get your Publisher ID. You can also use "Get sharing tools" wizard on ShareThis.com to generate button code and get publisher ID without registration.</help>
        </property>
      </common>
    </pagetypes>
  </language>
</languages>

It’s a bit strange to describe block properties in pagetypes structure; hopefully it will be fixed in one of the next platform updates.

Module manifest for add-on

Add-on assembly is explicitly specified in module.config file to avoid automatic discovering of available assemblies in add-on bin folder.

Restricting prerequisites version

Dependency on EPiServer assembly is specified in add-on nuspec file. For this version the prerequisite is more strict and it requires EPiServer platform from version 7.0 (including) up to 7.1 (excluding) to avoid any incompatibility with new platform releases.

<?xml version="1.0"?>
<package >
  <metadata>
    <id>$id$</id>
    <title>Sharing Wigdet</title>
    <version>$version$</version>
    <authors>$author$</authors>
    <owners>$author$</owners>
    <projectUrl>https://github.com/dmytroduk/SharingWidgetAddOn</projectUrl>
    <iconUrl>http://w.sharethis.com/images/sharethis_32.png</iconUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Enables site visitors to share the content in social networks and communities using ShareThis.com widget.</description>
    <tags>EPiServerPublicModulePackage Social Sharing ShareThis</tags>
    <dependencies>
      <dependency id="EPiServer" version="[7.0,7.1)" />
    </dependencies>
  </metadata>
</package>

Creating add-on package after build

Project file contains after build target which creates new add-on package every time you rebuild the project.

<?xml version="1.0" encoding="utf-8"?>
<Project ...>
<!-- ... Ommited project file content ... -->

  <Target Name="CreateAddOnPackage">
    <PropertyGroup>
      <NuGetExePath>..\Dependencies\NuGet.exe</NuGetExePath>
    </PropertyGroup>
    <Exec Command="&quot;$(NuGetExePath)&quot; pack $(ProjectFileName) -OutputDirectory $(OutDir)" Condition="Exists('$(NuGetExePath)')" />
  </Target>
  <!-- Creating add-on package after build. -->
  <Target Name="AfterBuild">
    <CallTarget Targets="CreateAddOnPackage" />
  </Target>
</Project>

NuGet command line tool should be placed in Dependencies folder on solution root level.

Known issue with add-on block rendering on MVC site

There is a known issue with shared block rendering when the block is deployed as an add-on/module on EPiServer 7 MVC site. You will get similar error when viewing a block or page that contains add-on block in content area:

Server Error in '/TestMvc' Application. 
--------------------------------------------------------------------------------
The controller for path '/TestMvc/UIPath/CMS/en/,,183_207/' was not found or does not implement IController.

Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code. 

Exception Details: System.Web.HttpException: The controller for path '/TestMvc/UIPath/CMS/en/,,183_207/' was not found or does not implement IController.

Source Error: 

Line 23:         public virtual void RenderAction(HtmlHelper helper, string action, string controller, object routeValues)
Line 24:         {
Line 25:             helper.RenderAction(action, controller, routeValues);
Line 26:         }
Line 27:     }

As far as I can see the problem is that MVC has a cache of known controllers and this cache is created based on the list of assemblies defined in system.web/compilation/assemblies section in web.config. It also includes the main application assembly that is associated with global.asax code.

MVC uses that cache to find block controller by name convention (FooBlock -> FooBlockController) and it fails because controllers from module/add-on assemblies are not listed in that cache since add-on system does not change the configuration files.

This issue is fixed and the fix should be available in the next platform update. For now you can try following workarounds.

Simple workaround

The simple workaround is to add add-on assembly in web.config manually:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
… 
  <system.web>
    <compilation … >
      <assemblies>
         …
        <add assembly="EPiServer.Samples.SharingWidget" />
      </assemblies>
    </compilation>
  </system.web>
</configuration>

Tricky workaround

Second workaround for real geeks is to implement initialization class which registers required add-on/module assembly programmatically. For example, it could register all assemblies in modulesbin folder to fix this issue for all add-ons.

This initialization class should be marked with PreApplicationStartMethodAttribute and the assembly with this code should reside in site bin folder. Please see more information about this attribute here.

Fixing block rendering issues in Alloy Templates for EPiServer 7

Mon, 19 Nov 2012 18:46:00 GMT

New Alloy templates package for EPiServer 7 is a good example of building adaptive site and using new EPiServer features like shared blocks. It implements custom content area rendering to arrange blocks in rows and fill all available space depending on current browser size. There is couple of known issues related to these rendering tricks.

Symptoms

Postback handler in block control is not triggered.

Controls in block template are not always initialized properly.

Steps to reproduce

Add dummy block definition:

[ContentType]
public class PostbackBlock : BlockData
{
}

Create user control as rendering template for this block type. Add some input controls and submit button in block template. Let’s ping Santa:

<%@ Control Language="C#" AutoEventWireup="true" 
    CodeBehind="PostbackBlockControl.ascx.cs"
    Inherits="EPiServer.Templates.Alloy.Views.Blocks.PostbackBlockControl" %>
<asp:Panel runat="server">
    <asp:TextBox runat="server" ID="Message"></asp:TextBox>
    <asp:RequiredFieldValidator runat="server" Text="*" 
        ControlToValidate="Message"  />
    <asp:Button runat="server" Text="Send" OnClick="OnClick" />
</asp:Panel>
<asp:Panel ID="SentMessagePanel" runat="server" Visible="false">
    <p>Ok, it looks like you've been good boy/girl this year. Sent to Santa:</p>
    <p><asp:Literal runat="server" ID="SentMessage"></asp:Literal></p>
</asp:Panel>

Implement postback handler for button click event.

public partial class PostbackBlockControl : BlockControlBase<PostbackBlock>
{
    protected void OnClick(object sender, EventArgs e)
    {
        if (Page.IsValid)
        {
            // TODO: Deliver message to Santa

            SentMessagePanel.Visible = true;
            SentMessage.Text = Message.Text;
        }
    }
}

In Edit mode create new shared block, drop it to the content area on the page, publish and try to submit your form in view mode. Note that your on-click handler is not executed.

Solution

Only a couple of code lines needs to be fixed, please see it highlighted below.

Creating controls in time

All block controls in Alloy project implement IBlockControl interface to define block width and ensure nice Tetris-like effect when block is rendered. If your block control does not implement IBlockControl interface it is automatically wrapped in GenericIBlockControlWrapper control to provide default minimum and maximum width. The side effect of this wrapping is that controls are created too late (usually on PreRender stage) and postback handlers in wrapped block controls are never triggered.

First you have to add public method to ensure that child controls are created in GenericIBlockControlWrapper:

public class GenericIBlockControlWrapper : WebControl, IBlockControl
{
    // ...
    // Ommited GenericIBlockControlWrapper code...
    // ...

    /// <summary>
    /// Ensures that child controls are created.
    /// </summary>
    public void EnsureChildControlsCreated()
    {
        EnsureChildControls();
    }
}

Then you need to call this method when block control is wrapped in GetIBlockControl method of SitePropertyContentAreaControl:

public class SitePropertyContentAreaControl : PropertyContentAreaControl
{
    // ...
    // Ommited SitePropertyContentAreaControl code...
    // ...

    /// <summary>
    /// Gets the control responsible for rendering content and tries to cast it to <see cref="IBlockControl"/>.
    /// If the control does not implement this <see cref="IBlockControl"/> we create a wrapper that handles this for us.
    /// </summary>
    private static IBlockControl GetIBlockControl(ContentRenderer contentRenderer)
    {
        var blockControl = contentRenderer.CurrentControl as IBlockControl;

        if (blockControl != null)
        {
            return blockControl;
        }

        var genericIBlockControlWrapper = new GenericIBlockControlWrapper();

        genericIBlockControlWrapper.InnerControl = contentRenderer.CurrentControl;
        genericIBlockControlWrapper.CurrentData = contentRenderer.CurrentData;
        genericIBlockControlWrapper.ContentRenderer = contentRenderer;
        contentRenderer.CurrentControl = genericIBlockControlWrapper;

        // Create controls in time:
        genericIBlockControlWrapper.EnsureChildControlsCreated();

        return genericIBlockControlWrapper;            
    }

    // ...
    // Ommited SitePropertyContentAreaControl code...
    // ...

}

Now block controls are created in time (before Load stage on postback) and ASP.NET can find and trigger postback handlers.

Avoiding adding block row twice

Second problem is that last row of the blocks in the content area is mistakenly added to control tree twice. It’s not so obvious because blocks in that row are rendered only once, but it can cost various problems with control initialization. In my case there were issues with view state and validation in complex web control.

Find GetBlockGroups method in SitePropertyContentAreaControl class and clean block group list when last row is created. Here is full listing of GetBlockGroups method, updated code is highlighted:

public class SitePropertyContentAreaControl : PropertyContentAreaControl
{
    // ...
    // Ommited SitePropertyContentAreaControl code...
    // ...

    /// <summary>
    /// Composes groups where each group represents a Bootstrap row of blocks
    /// </summary>
    /// <param name="contentRenderers"></param>
    /// <returns></returns>
    private List<List<ContentRenderer>> GetBlockGroups(IList<ContentRenderer> contentRenderers)
    {
        var groups = new List<List<ContentRenderer>>();

        var group = new List<ContentRenderer>();

        var minimumWidthOfBlockControlsAddedToCurrentGroup = 0;

        for (int i = 0; i < contentRenderers.Count; i++)
        {
            var contentRenderer = contentRenderers[i];

            // Add block controls to the current group

            var blockControl = GetIBlockControl(contentRenderer);

            // There is no point in showing the default block control in preview mode, or if the current user isn't an editor
            if (blockControl is DefaultBlockControl)
            {
                if (Page is BlockPreview || !CurrentPage.QueryDistinctAccess(AccessLevel.Edit))
                {
                    continue;
                }
            }

            if (blockControl.MinimumWidth > RowWidth)
            {
                _logger.WarnFormat("Block control '{0}' has a minimum width of {1} and won't properly fit within the maximum row width which is {2}", blockControl.GetType().Name, blockControl.MinimumWidth, RowWidth);

                if (Page is BlockPreview) // In block preview mode we skip block controls that won't fit within the current row width
                {
                    continue;
                }
            }

            blockControl.Width = blockControl.MinimumWidth;

            group.Add(contentRenderer);

            minimumWidthOfBlockControlsAddedToCurrentGroup += blockControl.MinimumWidth;

            if (i == contentRenderers.Count - 1) // The last block has been added, so we're done creating groups
            {
                // Fill out the last row
                AdjustWidthOfBlocksToFillRow(group);
                groups.Add(group);
                // Clean the last row list
                group = null;
                break;
            }

            var nextContentRenderer = contentRenderers[i + 1];

            if (nextContentRenderer != null)
            {
                var nextBlockControl = GetIBlockControl(nextContentRenderer);

                if (minimumWidthOfBlockControlsAddedToCurrentGroup + nextBlockControl.MinimumWidth <= RowWidth)
                {
                    continue;
                }

                // The next block won't fit in this group, try to fill the group by increasing the size of already added blocks
                AdjustWidthOfBlocksToFillRow(group);
            }

            groups.Add(group);

            group = new List<ContentRenderer>();

            minimumWidthOfBlockControlsAddedToCurrentGroup = 0;
        }

        // Check that row list is not null
        if (group != null && group.Count > 0)
        {
            //If we somehow escaped the loop without adding the last group lets do it now.
            AdjustWidthOfBlocksToFillRow(group);
            groups.Add(group);
        }

        return groups;
    }

    // ...
    // Ommited SitePropertyContentAreaControl code...
    // ...
}

Result

Now you can post a message using shared block:

More information

Bug #91643 is filed for these issues and the fix should be available in the next Alloy templates update. Until then you can use described workaround. Please let us know if it works for you.

EPiServer 7 CMO

Fri, 02 Nov 2012 20:43:00 GMT

EPiServer 7 is out! CMO is also available in the main installation package, go and download it.

What’s new in EPiServer 7 CMO

CMO is included in EPiServer 7 CMS license

If you have EPiServer 7 CMS license you get EPiServer 7 CMO for free. No additional license is required. Enjoy!

Ready for MVC and Web Forms

EPiServer 7 supports both Web Forms and MVC. You can even mix these technologies in your solution. CMO works on both Web Forms and MVC based sites.

Please make sure that statistics tracking scripts are included in your pages.

Deployment improvements

Now it’s possible to select existing database when installing CMO. For instance, you may decide to use your existing CMS database and don’t create separate one for CMO.

Live Monitor integration is available as separate installation option.

Enable it if you want to see real-time user activity in campaign reports. It will install Live Monitor on target site automatically. This option is not available if you don’t have Live Monitor installed on the server. You can run Live Monitor .msi installer later and reinstall CMO+Live Monitor integration on site afterwards.

Bug fixes

EPiServer 7 CMO includes the number of bug fixes and improved performance.

Notes and tips

Statistics tracking

EPiServer Framework includes new small framework developed to manage client resources and inject stuff on pages. We use it to track statistics for CMO and Live Monitor.

Please consider best practice guidelines, requirements for page templates and upgrading documentation to make sure that statistics tracking scripts are available on your site.

Creating page versions for A/B testing

EPiServer 7 CMS comes with new brand editing UI and one of the ideas is that you are always editing and working on last draft.

You may want to create several page versions to run A/B test. It’s pretty easy, just start editing your original page. New draft is created automatically and you can use it as page version in A/B test:

You can create more versions as follows:

Add Versions gadget on panel in Edit mode:

Select published version (your original page) in the list:

Click on “New Draft from here” option in Options button in main toolbar:

New draft is created and you can edit page version for your test. Penguins are nice, right?

Mark your page versions as “Ready to Publish”.

A/B tests and shared blocks

Let’s say you have a page and shared block is placed in one of the content area on the page. Probably you would like to run A/B test for this page and see which block version gives you the best result.

A/B testing for shared blocks is not fully supported by the current CMO version and the page is rendered with published block version.

You can create several shared blocks and place them on corresponding page versions. In this case you are testing page versions that hold different blocks.

More information

You can find more information about EPiServer 7 CMO in the following documents:

Installation Instructions – EPiServer 7 CMO

Upgrading guide

CMO section in EPiServer 7 SDK

User guide

Developing simple add-on for EPiServer 7 Preview

Wed, 27 Jun 2012 13:41:00 GMT

This blog post provides brief technical information about Add-On Store in EPiServer 7 Preview and describes the process of developing simple add-on step by step.

Meet the Add-On Store

Add-on Store is the new approach to create, distribute, share and manage modules for EPiServer based sites.
For site owners and administrators Add-On Store is the one place where they can find, install and manage required add-ons to bring new features and tools for site visitors and editors.

For EPiServer partners and developers Add-On Store means the standard way to create and distribute modules, plug-ins and extensions for EPiServer sites.

And we use this technology ourselves. It may be worth mentioning that new Edit UI and UI Platform in EPiServer 7 Preview are add-ons. Add-On system itself is implemented as add-ons. It proves that add-ons can be really powerful.

Go ahead, download EPiServer 7 Preview and see it in action.

Add-ons from developer point of view

Please look at the documentation for add-on developers in EPiServer Framework SDK Knowledge Base to get more information, technical details and things that should be kept in mind when you are developing add-on.

What can be an add-on

Technically add-on is a Shell module that is distributed as NuGet package and can be installed, updated and removed using Add-On Store interface on EPiServer 7 site. Each add-on resides in the one directory.

Add-on provides new functionality and extensions for EPiServer sites: various plug-ins, scheduled jobs, gadgets, Editing UI components, data stores, typed pages, blocks, templates and so on.

Configuration file changes are not supported in this version. I’m not sure if it is good idea to make it possible in the future.

Initialization and extension point

It is possible to implement specific initialization for add-on components and execute custom code when add-on is installed, updated or removed.

Public, protected and system add-ons

Public add-ons provide functionality for the public site.

Protected add-ons usually bring features for site administrators and editors and contain resources that should not be available publicly.

System add-ons are important system modules that cannot be removed, but can be updated. Usually it is EPiServer add-ons that are distributed with the platform and deployed on each new web site. For example: new Editing Interface in EPiServer 7 Preview.

Add-on prerequisites and dependencies

Dependencies are the list of other add-ons that should be installed on the site. The system makes sure that you will not break any installed add-ons by updating or removing related packages. Dependencies are installed and upgraded automatically if possible.

Add-on system allows installing only those add-ons that are compatible with your environment.

Prerequisites are dependencies to the products that are not installed as add-ons. For example, you probably would define EPiServer Community as prerequisite for the add-on that provides some new great widgets to manage Community entities.

Sample add-on: Sharing Widget

This sample add-on makes it easy for site visitors to share the content using ShareThis widget which allows to recommend things in tons of social networks and communities.

To try something new sharing widget is implemented as shared block that can be simply dropped on the site pages in new EPiServer 7 Edit UI.

Getting ShareThis widget code

Go to ShareThis site and generate default widget with small buttons for generic web site and pick 4 favorite social networks: Twitter, Facebook, Google+ and LinkedIn. All other communities will be available through ShareThis option.

You will be prompted to register in order to get Publisher ID. Using this account you can access a set of analytic tools to understand sharing behavior. It’s possible to skip the registration and just get a code, in this case you still get some Publisher ID but you don’t have access to analytics. Make sure that ShareThis terms of service and privacy policy are fine with you.

Save generated code on the last step for further use:

<span class='st_twitter' displayText='Tweet'></span>
<span class='st_facebook' displayText='Facebook'></span>
<span class='st_googleplus' displayText='Google +'></span>
<span class='st_linkedin' displayText='LinkedIn'></span>
<span class='st_sharethis' displayText='ShareThis'></span>

<script type="text/javascript">var switchTo5x=true;</script>
<script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script>
<script type="text/javascript">stLight.options({publisher: "Your-Publisher-ID"}); </script>

Creating add-on project

Create new ASP.NET Empty Web Application project using Visual Studio. You can remove web.config file in the project root and the most of default references.

References to the following assemblies need to be added:

EPiServer
EPiServer.BaseLibrary
EPiServer.Data
EPiServer.Shell
System.ComponentModel.DataAnnotations
System.Web.Mvc

Hopefully, platform binaries will be available in the EPiServer NuGet feed after EPiServer 7 release and it will be possible to reference corresponding NuGet package. Right now you can just create Dependencies directory in the solution folder and copy referenced EPiServer assemblies.

Adding block type

Create BlockTypes folder inside your project and add new class SharingWidgetBlock:

ContentType(DisplayName = "Sharing Widget Block", 
    Description = "Adds ShareThis widget on pages where block is placed.")]
public class SharingWidgetBlock : BlockData
{
    [Display(Name = "Publisher ID",
        Description = "Register on ShareThis.com to get your Publisher ID.")]
    [Required]
    public virtual string PublisherID { get; set; }
}

EPiServer.DataAnnotations.ContentTypeAttribute is applied to mark the content type and define the name and description that are displayed when this block type is listed in Admin mode.

EPiServer.Core.BlockData class provides the base implementation for all block types.

PublisherID property is the only one setting for sharing widget block and it is marked as required. DisplayAttribute is used to define property name and description that will appear in EPiServer Edit and Admin mode.

Implementing block rendering

EPiServer 7 Preview brings full MVC support and the great thing here is that you can have Web Forms and MVC working side by side.

Obviously your add-on is going to be so awesome that most of EPiServer site owners will dream about installing it on their EPiServer 7 sites, right? Of course it should support both Web Forms and MVC!

Web Forms control

Add Blocks sub folder in the project and create new user control SharingWidget.ascx.

Change control code-behind file and inherit BlockControlBase<SharingWidgetBlock> which is the base class for user controls that renders block data:

public partial class SharingWidget : BlockControlBase<SharingWidgetBlock>
{
}

Add ShareThis widget code to control markup.

Note that add-on assembly is referenced in the Control directive. This is required since add-on binaries are not placed to site bin folder and will be loaded from probing path.

<%@ Control Language="C#" AutoEventWireup="false" CodeBehind="SharingWidget.ascx.cs" 
    Inherits="EPiServer.Samples.SharingWidget.Blocks.SharingWidget, EPiServer.Samples.SharingWidget" %>

<script type="text/javascript">    var switchTo5x = true;</script>
<script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script>
<script type="text/javascript">    stLight.options({ publisher: "<%= CurrentBlock.PublisherID %>" }); </script>

<span class='st_twitter' displayText='Tweet'></span>
<span class='st_facebook' displayText='Facebook'></span>
<span class='st_googleplus' displayText='Google +'></span>
<span class='st_linkedin' displayText='LinkedIn'></span>
<span class='st_sharethis' displayText='ShareThis'></span>

CurrentBlock property is used to access block instance that is being rendered by this user control and set publisher ID widget parameter.

MVC block rendering

Model

You already have it: SharingWidgetBlock is the model.

View

Add standard Views folder in the project. Create SharingWidget sub folder and add SharingWidget.cshtml partial view. It follows naming conventions for MVC views, however it is not really important in this particular case.

SharingWidget.cshtml view code looks like this:

@model EPiServer.Samples.SharingWidget.BlockTypes.SharingWidgetBlock
           
<script type="text/javascript">    var switchTo5x = true;</script>
<script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script>
<script type="text/javascript">    stLight.options({ publisher: "@Model.PublisherID" }); </script>

<span class='st_twitter' displayText='Tweet'></span>
<span class='st_facebook' displayText='Facebook'></span>
<span class='st_googleplus' displayText='Google +'></span>
<span class='st_linkedin' displayText='LinkedIn'></span>
<span class='st_sharethis' displayText='ShareThis'></span>

As you can see, it uses Razor syntax to output publisher ID and contains the same HTML as user control.

To make it work add web.config file to the Views folder. It configures Razor engine and makes add-on assembly and namespace available in the views as follows:

<?xml version="1.0"?>
<configuration>
  <configSections>
    <sectionGroup name="system.web.webPages.razor" type="System.Web.WebPages.Razor.Configuration.RazorWebSectionGroup, System.Web.WebPages.Razor, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35">
      <section name="host" type="System.Web.WebPages.Razor.Configuration.HostSection, System.Web.WebPages.Razor, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" />
      <section name="pages" type="System.Web.WebPages.Razor.Configuration.RazorPagesSection, System.Web.WebPages.Razor, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" />
    </sectionGroup>
  </configSections>

  <system.web.webPages.razor>
    <host factoryType="System.Web.Mvc.MvcWebRazorHostFactory, System.Web.Mvc, Version=4.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" />
    <pages pageBaseType="System.Web.Mvc.WebViewPage">
      <namespaces>
        <add namespace="EPiServer.Samples.SharingWidget" />
      </namespaces>
    </pages>
  </system.web.webPages.razor>

  <system.web>
    <compilation>
      <assemblies>
        <add assembly="EPiServer.Samples.SharingWidget" />
      </assemblies>
    </compilation>
  </system.web>
</configuration>

Controller

Create controller responsible for block data rendering:

public class SharingWidgetController : BlockController<SharingWidgetBlock>
{
    public override ActionResult Index(SharingWidgetBlock blockData)
    {
        return PartialView(Paths.ToResource(this.GetType(), "Views/SharingWidget/SharingWidget.cshtml"), blockData);
    }
}

There is a tiny trick to provide required view file.

BlockController<T> is the base class for block rendering controllers. Index method of base controller returns action result for partial view with the name equal to block type name. Then the system tries to find partial view in a folder structure according to the block namespace.

Search paths for EPiServer.Samples.SharingWidget.BlockTypes.SharingWidgetBlock type would be as follows:

~/Views/SharingWidget/SharingWidgetBlock.aspx
~/Views/SharingWidget/SharingWidgetBlock.ascx
~/Views/Shared/SharingWidgetBlock.aspx
~/Views/Shared/SharingWidgetBlock.ascx
~/Views/SharingWidget/SharingWidgetBlock.cshtml
~/Views/SharingWidget/SharingWidgetBlock.vbhtml
~/Views/Shared/SharingWidgetBlock.cshtml
~/Views/Shared/SharingWidgetBlock.vbhtml
/Util/Views/Shared/SharingWidgetBlock.ascx
/Util/Views/Shared/DisplayTemplates/SharingWidgetBlock.ascx
/Util/Views/Shared/EditorTemplates/SharingWidgetBlock.ascx
/EPiServer/CMS/Views/Shared/SharingWidgetBlock.ascx
/EPiServer/CMS/Views/Shared/DisplayTemplates/SharingWidgetBlock.ascx
/EPiServer/CMS/Views/Shared/EditorTemplates/SharingWidgetBlock.ascx

Most probably add-on view file will not be found in these folders, so the system needs some help to locate it.
The path to the directory where add-on is installed depends on packaging configuration and add-on developer should never hardcode absolute and concrete paths. Full paths to add-on resources like scripts, styles and views should be resolved from the path relative to the add-on directory. EPiServer.Shell.Paths class provides the bunch of methods to resolve path to resources located in the corresponding add-on folder. Add-on can be identified by name, by assembly or by type from add-on assembly.

Controller for sharing widget block overrides default Index method to resolve the view path using partial path in add-on directory.

Intermediate results

You have implemented block type, Web Forms and MVC rendering templates and this code can be deployed as Shell module on the site.

I agree, it’s nasty to have that script tags in both markups; you get several script includes if there are several controls/views rendered on the page. But don’t worry about it too much. Probably you won’t have several sharing widgets on page unless your site looks like this.

And of course it would be nice to make the style of the widget and the list of available buttons configurable. Again, keep it simple for the version one.

Creating add-on package

To turn the module into an add-on you need to create a NuGet package that contains add-on assemblies and resources.

Download NuGet command line or Package explorer from NuGet CodePlex.

There are several approaches to creating a NuGet package. Creating a package from a project looks like the easiest way for this simple add-on.

Creating package manifest file

Run following command in the directory where the .csproj file is:

nuget spec

It creates NuGet .nuspec manifest file for add-on package. Manifest file can be included to the project for convenience.

Package metadata

Edit .nuspec file, add basic metadata like add-on title, description, tags, icon URL etc.

Note that it contains replacement token $id$ , $version$ and $author$ that are going to be replaced by assembly name, version and author when NuGet builds the package:

<?xml version="1.0"?>
<package >
  <metadata>
    <id>$id$</id>
    <title>Sharing Wigdet</title>
    <version>$version$</version>
    <authors>$author$</authors>
    <owners>$author$</owners>
    <projectUrl>https://github.com/dmytroduk/SharingWidgetAddOn</projectUrl>
    <iconUrl>http://w.sharethis.com/images/sharethis_32.png</iconUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Enables site visitors to share the content in social networks and communities using ShareThis.com widget.</description>
    <tags>EPiServerPublicModulePackage Social Sharing ShareThis</tags>
    <dependencies>
      <dependency id="EPiServer" version="[7.0,8.0)" />
    </dependencies>
  </metadata>
</package>

Public or protected add-on

It’s required to add one of the special tags to indicate that this is add-on package for EPiServer based site:

EPiServerPublicModulePackage- this tag should be added for public add-ons
EPiServerModulePackage - should be added in the tag list of protected add-ons

EPiServerPublicModulePackage tag is more suitable for this add-on since sharing widget should be available for all site visitors.

Dependencies and prerequisites

Sharing Widget add-on does not depend on any other add-on, so you could skip dependencies list.
However, it can be used to set add-on prerequisites. Define that this add-on requires any version of EPiServer CMS 7. Add dependency with id equal to EPiServer core assembly name and version range from 7 (including) to 8 (excluding). Add-on system will check if corresponding assembly is loaded in site app domain.

Building the package

Build the project.

Run following command to create the package from the add-on project:

nuget pack EPiServer.Samples.SharingWidget.csproj

It creates add-on package EPiServer.Samples.SharingWidget.1.0.0.0.nupkg that is ready to be installed.

Installing Sharing Widget add-on

Sharing Widget add-on is not published in the central EPiServer Store (yet!), you have to upload package file to install it on site. Click on “Manual Upload” button, select package file and press Install. You will be prompted to restart the site to finish the installation.

After successful installation Sharing Widget add-on should be displayed in installed section. You can remove it any time (why would you?) by clicking on Uninstall button in detailed view.

Using add-on widget

Creating shared block

Navigate to new shiny Edit UI. Make sure that you have Shared Blocks widget in the right panel. Create new Sharing Widget block, specify your publisher ID and publish.

Placing widget on pages

Drag Shared Widget block and drop it on the appropriate content area. Publish the page.

Check out that sharing widget works both on Web Forms and MVC site:

Source code

Source code is available on GitHub, you are more than welcome to download or fork. Add-on package can be downloaded here.

Try it!

Hopefully the above example would encourage you to start developing your add-ons right now and make new great things.

Your feedback is highly appreciated and would help to make add-on system and EPiServer 7 better.

EPiServer CMO in load balancing environment with separate editing server

Sat, 28 Jan 2012 18:54:00 GMT

This blog post describes EPiServer CMO installation and configuration in a load balanced environment where CMS editing interfaces and components are not available on the front-end web servers; additional editing server is set up and attached to the same database.

This kind of environment is described in this blog post as Option 2.

So let’s consider the following deployment model:

Web site based on EPiServer CMS is installed on two or more front web servers. The site is available publicly through the load balancing system. CMS management UI is disabled on these public sites.
Separate editing web server is set up behind the firewall. Web site is deployed on editing server with EPiServer CMS editor and admin UI and uses the same data and file shares as sites deployed on front-end servers. Editing server is available within internal network for editors and administrators.
There is one back-end server which contains the one shared site database.

EPiServer CMO deployment should follow that schema.

CMO Core, Statistics handler and web services are installed on each front-end web server.

These components and also CMO UI are installed on separate editing server. Load balancing configuration with sticky sessions is not required by CMO UI in this case. Statistics gathering on editing server can be turned off to process only public site visits.

CMO database and Aggregation service are installed on the back-end server, where CMS database is hosted. One CMO database is shared between all front-end servers and editing server.

Thumbnail service must be accessible for CMO UI components. Since CMO UI is installed only on the editing server, there are at least 2 options where to deploy Thumbnail service: on the editing server or on the back-end server, as it was described in the previous blog post.

Keeping in mind that Thumbnail service needs to access web site and all site resources to make a screenshot, we can install Thumbnail service on the editing server, where we obviously need to have access to web site and its resources. In this case there is no need to enable access from back-end server to web site or Internet, which is good for the security. You can decide where to install Thumbnail service depending on your environment and configuration.

URL rewrite provider is used to resolve external page URL. Thumbnail service most likely will create screenshots on the site hosted on the editing server and will use the URL specified in siteUrl attribute of episerver/sites/site section as a base address when standard FURL provider is enabled on the site.

Please see the steps required to install and configure EPiServer CMO below.

Installing EPiServer CMO in load balancing environment with separate editing server

1. Install CMO module on the front-end servers and the editing server using EPiServerCMO.msi installer.

2. Deploy CMO on web site on the first front-end server using Deployment Center. Follow installation instructions.

Select only Statistics Handler in optional components list to install.

Select or enter the name of SQL Server instance on your back-end server on database settings installation step.

Enter the name of new CMO database to create. Enter the name and password of database user.

You can leave the default Thumbnail service URL (http://localhost:8731/IECaptWCF/Url2Image).

3. Deploy CMO on web site on all other front-end servers.

Do the same as you did on step 2, but don’t create new database this time. Select existing CMO database and enter the same user name and password that was created on the previous step.

4. Deploy CMO on web site on the editing server using Deployment Center.

Select Campaign Monitor and Optimization UI, Statistics Handler and Thumbnail Service in optional components list to install:

You can uncheck Statistics Handler option and don’t install it if visitors of web site on the editing server should not affect CMO statistics. However there is also another way of disabling statistics gathering which is described in the next installation step.

Choose SQL Server instance on your back-end server on database settings installation step.

Don’t create new database, select existing CMO database that was created on the previous steps. Enter the name and password of database user specified on the step 2.

5. Consider disabling of statistics gathering on the editing server if visitors of web site on the internal editing server should not affect CMO statistics.

Add the following setting to /configuration/appSettings node in web.config file to disable CMO statistics gathering on the site:

  <appSettings>

    <add key="DisableCmoStatisticGathering" value="true" />

  </appSettings>

6. Update configuration of sites where CMO was installed to support .NET 4 if it is required. Do it on all front-end and editing servers.

7. Configure CMO Live Monitor for multiple bindings on all front-end and editing servers.

8. Consider additional configuration if Thumbnail service is installed on Windows Server 2008 R2.

9. Install and configure Aggregation service on the back-end server. Please look at the installation instructions.

Point the Aggregation service to the CMO database that is used on the web sites.

10. Consider after-installation steps and notes.

Verify that secretkey values in appSettings section are equal in Thumbnail service configuration file and in web.config files on the site where CMO UI is installed.

Verify Thumbnail service URL in CMO / Settings / Page Thumbnails section, make sure that Thumbnail service is available for CMO UI components on the editing server and that service can access web site and site resources to generate screenshots.

Verify that Statistics handler URL in CMO / Settings / General section is valid and handler is accessible for public site visitors.

Licensing

Separate EPiServer CMO license is required on each site where CMO is installed.

Other deployment scenarios

Described deployment model can be changed depending on your environment and configuration. For example, you can consider installing Aggregation service on the editing server, if you don’t expect heavy loading on that machine. You can try to find better host for Thumbnail service in your network.

Initial environment can be more complex. Load balancing can be applied to internal database servers or editing servers. These options will affect CMO deployment.

More information

Please see the following blog posts and documents for more information:

EPiServer CMO components and simple installation scenario.

EPiServer CMO: advanced deployment options and manual component installation.

EPiServer CMO in load balancing environment: simple scenario.

Page screenshots in EPiServer CMO and Thumbnail service configuration.

EPiServer CMO documentation.

Feedback

Please feel free to let us know about your case and how how things work in your environment. Your feedback is highly appreciated.

EPiServer CMO in load balancing environment: simple scenario

Tue, 17 Jan 2012 17:48:00 GMT

Load balancing is a clear choice for the most of popular sites with high volumes of incoming traffic. This solution allows distributing the load among several servers to improve performance and achieve high availability.

This blog post describes а simple case of EPiServer CMO installation and configuration in the hosting environment where load balancing is applied to the web servers.

Let’s consider the following deployment model:

Web site based on EPiServer CMS is installed on two or more front web servers. The site is available publicly through the load balancing system, which spreads the work between those servers.
EPiServer CMS editor and admin UI is deployed on each web server and available through the load balancing system.
There is one back-end server which contains one shared site database.

The simplest deployment scenario for EPiServer CMO in this environment looks pretty similar to that one described in the previous blog post, the difference is that now we have several front web servers.

CMO Core, Statistics handler, web services and CMO UI are deployed on each front-end server. CMO database, Aggregation and Thumbnail services are installed on one back-end server, where CMS database is hosted. One CMO database is shared between all front-end servers.

Please see the steps required to install and configure EPiServer CMO below.

Installing EPiServer CMO in the load balancing environment

1. Install CMO on all web servers where the site is hosted using EPiServerCMO.msi installer.

2. Deploy CMO on the site on the first web server using Deployment Center. Follow installation instructions.

Select Campaign Monitor and Optimization UI and Statistics Handler in optional components list to install:

Select or enter the name of SQL Server instance on your back-end server on database settings installation step.
Enter the name of new CMO database to create.

3. Deploy CMO on the site on other web servers.

Select the same optional components to install: Campaign Monitor and Optimization UI and Statistics Handler.

Choose SQL Server instance on your back-end server on database settings installation step.

Don’t create new database this time, select existing CMO database that was created on the previous steps.

4. Update configuration of sites where CMO was installed to support .NET 4 if it is required.

5. Configure CMO Live Monitor for multiple bindings.

6. Install and configure Thumbnail Service on back-end server manually.

Thumbnail service should be able to access the site through the load balancing system and all site resources that are required to create page screenshots. Make sure that Thumbnail service can be accessed from all web servers where CMO UI is installed.

Consider additional configuration if service is installed on Windows Server 2008 R2. Please see this blog post for more information about Thumbnail service.

7. Install and configure Aggregation service on back-end server manually. You can find installation instructions here.

Point Aggregation service to the CMO database that is used on the web sites.

8. Consider after-installation steps and notes.

9. Make sure that load balancing is configured to use sticky sessions, it is required by CMO UI.

More information

Please see the following blog posts and documents for more information:

EPiServer CMO components and simple installation scenario.

EPiServer CMO: advanced deployment options and manual component installation.

Page screenshots in EPiServer CMO and Thumbnail service configuration.

EPiServer CMO documentation.

Feedback

Your feedback is highly appreciated. Please let me know how it works in your case.

EPiServer CMO: advanced deployment options

Wed, 21 Dec 2011 17:37:00 GMT

This blog post describes several options for advanced EPiServer CMO deployment.

You may have more than one server, for example when site database is hosted on the separate back-end machine. You can consider the following options to distribute the work across servers:

CMO database on the separate server. It sounds logically to keep CMO database on the same server as site data.
Aggregation service on the separate server. Most likely your database server could be a good host for it.
Thumbnail service on the separate server. There are 2 important requirements: Thumbnail service should be able to access web sites to make screenshots; and CMO UI should be able to access Thumbnail service to request page screenshots for reports.
Standalone Statistics Handler. All pages from any active CMO campaign contain script injection to collect visitor’s statistics. This data is sent to CMO Statistics handler which is installed on site by default. It is possible to host Statistics Handler in standalone web application and on the separate server, if you want to process incoming visitors statistics separately and don’t load the main front server with that. However, this option is not really interesting. The thing is that standalone Statistics Handler should be publicly available, so it should be deployed on some of the front servers. If you have several front servers, you will probably configure load balancing for them. In this case the idea to host standalone Statistics handler doesn’t sound very practical.

Having one front-end web server and one back-end database server, you probably end up with the following deployment model.

You can find information on how to implement each option below. EPiServer CMO 2 R2 does not provide separate installer for services. Aggregation and Thumbnail services can be installed and configured automatically when you install CMO on specific web site, but these services have to be installed manually on back-end server.

CMO database on the separate server

It’s easy. During installation you can create CMO data on local or remote machine, so you can just define your back-end server on “Database settings” step when you install EPiServer CMO on web site using Deployment Center.

Aggregation service on the separate server

Uncheck “Aggregation Service” option when you are installing CMO on web site using Deployment Center. Service will not be installed on your front server, but you can find service binaries in CMO installation directory: C:\Program Files (x86)\EPiServer\EPiServer\CMS\6.1.379.0\Install\Modules\CMO2.1.0.93\bin

You will need to install and configure CMO Aggregation service manually on back-end machine. Service installation and configuration are described in this document.

Thumbnail service on the separate server

Thumbnail service doesn’t depend on other CMO parts and can be installed anywhere. Moreover, the one service can generate page screenshots for several web sites.

Uncheck “Thumbnail service” option when you are installing CMO on web site using Deployment Center. Thumbnail service will not be installed on front server; binaries can be found in CMO installation folder, by default it is C:\Program Files (x86)\EPiServer\CMS\6.1.379.0\Install\Modules\CMO2.1.0.93\Thumbnail Service\

Just copy that folder to another machine and install it as Windows service using installutil.exe.

Make sure that Thumbnail service can access web sites and site resources to generate screenshots. Service should be accessible for all CMO instances that are going to use it to show thumbnails in reports.

Secret key value in appSettings section must be equal in service configuration file and in web.config files on all sites.

Define new Thumbnail service URL in CMO Settings:

Standalone Statistics Handler

Uncheck “Statistics Handler” option when you are installing CMO on web site using Deployment Center.

Use this document to install and configure CMO Statistics handler as standalone application.

Make sure that CMO Statistics handler is publicly available and can receive data from site visitors.

Don’t forget to define new Statistics handler URL in CMO Settings:

More information

Please see the first blog post in this series for more information about CMO components, simple deployment model and after installation steps.

EPiServer CMO components and simple installation scenario

Mon, 19 Dec 2011 16:48:00 GMT

Running EPiServerCMO.msi you get CMO installed to EPiServer CMS module folder, by default it is C:\Program Files (x86)\EPiServer\CMS\6.1.379.0\Install\Modules\CMO2.1.0.93. Now it can be installed on specific web site using Deployment Center.

Installation instructions for EPiServer CMO 2 R2 pretty good describe simple deployment model with the one front server. By default all CMO components are deployed on the same machine and you get the following deployment schema:

Bellow are described main EPiServer CMO components to make this chart clearer.

EPiServer CMO components

It’s worth mentioning that it’s not about assemblies. Components are EPiServer CMO parts that communicates and cooperates with each other, these parts can be separated logically or/and by deployment.

CMO Core

Core is the heart of EPiServer CMO, all other parts depend on it. This is the central component that contains core logic for collecting and processing data.

CMO Statistics Handler

This component receives and processes raw visitor’s statistics and KPI data coming from client browsers.

CMO Web services

Currently CMO provides one web service that can be used by third party applications to update KPI values.

CMO Database

This is storage for EPiServer CMO data. By default it is separate database, but it is possible to create CMO data structures in the existing one.

CMO Aggregation Service

This is Windows service application responsible for data pre-calculation and aggregation. It allows to decrease database size and generate reports faster. The one Aggregation Service is able to process data from different CMO versions and can serve the number of CMO instances deployed on several sites.

CMO Thumbnail Service

This is Windows service application, which creates screenshots of site pages and provides thumbnails for reports. Check out this blog post for more information about CMO Thumbnail service.

CMO UI

CMO UI is user interface available for CMO administrators and users to manage LPO tests and campaigns, view reports, monitor statistics and configure settings.

CMO UI pages and resources are not copied on site during installation; it is connected via virtual path provider in the same way as CMS Edit/Admin UI.

After installation steps

Depending on your environment you may have to complete these additional steps after installation.

If you are going to run web site on .NET 4, please see Configuring EPiServer CMO 2 R2 to Support .NET 4.0
Configure CMO Live Monitor for multiple bindings
CMO Thumbnail service requires additional configuration if it is installed on Windows Server 2008 R2
Check access permissions in CMO Settings / Security page. By default only users in Administrators, WebAdmins or WebEditors roles have access to CMO UI and can manage the module.

Notes and tips

Friendly URL Rewriter module is required on site. CMO uses Friendly URL Rewriter events to inject scripts that collect visitor’s statistics.
View State must be enabled at least for CMO location.
If you face the exception related to ComponentArt stuff, try IIS reset.

Solving issue "405.0 - Method Not Allowed" when accessing WebDAV folder

Mon, 24 Oct 2011 17:00:00 GMT

Problem

Using EPiServer WebDAV you can face the following issue: after setting up WebDAV in EPiServer CMS and client configuration you still cannot access your web folder. Depending on client software you can get different error messages. Windows explorer says that it could not access your resource and suggests to check name spelling. Other clients return errors “Login failed” or something like “Directory listing denied”.

Investigating

To get more details you can enable server side logging for EPiServer WebDAV:

<?xml version="1.0" encoding="utf-8"?>

<log4net>

  <appender name="OutputDebugStringAppender" type="log4net.Appender.OutputDebugStringAppender">

    <layout type="log4net.Layout.PatternLayout">

      <conversionPattern value="%date [%thread] %-5level %type.%method - %message%newline" />

    </layout>

  </appender>

  <logger name="EPiServer.WebDav" additivity="false">

    <level value="Debug" />

    <appender-ref ref="OutputDebugStringAppender" />

  </logger>

</log4net>

DAV Explorer can be used to get detailed log with all sent and received messages on client side.

In my case it turned out that EPiServer.WebDAV.Handler was processing only first OPTIONS requests.

Second request PROPFIND didn’t reach our handler. In respond to PROPFIND client got “405 Method Not Allowed” response from module named WebDAVModule. And this was the cause of the problem.

Cause

WebDAVModule intercepts WebDAV requests so they are not processed by EPiServer.WebDAV handler. Most likely it is not registered in your site config file. You can find it in Modules list for your web site in IIS Manager.

This is native IIS module, on my IIS it is enabled by default on each new web site.

Solution

Remove native WebDAVModule module if you don’t use it:

<configuration>

  <system.webServer>

    <modules>      

      <remove name="WebDAVModule" />

    </modules>

  </system.webServer>

</configuration>

After this EPiServer.WebDAV.Handler should be able to process all corresponding requests. WebDAV configuration guide is updated with this information.