Integrate Sitecore with Alexa

During last month’s Sitecore symposium I had the pleasure to present with my colleague Ben Adamski on expanding the reach of your Sitecore content with voice-activated assistants through an Alexa skill. This blog post will describe the integration discussed during this presentation and will provide some additional details.

Sitecore 9 omnichannel foundation

Sitecore has a solid omnichannel foundation which enables it to act as a headless CMS. Below diagram shows the main integration points exposed by Sitecore out of the box.

Omnichannel Foundation

  1. OData Item Service: this service can be used to query and retrieve any Sitecore item and retrieve it in JSON format.
  2. SXA Layout Service: the SXA layout service supports modelling content as JSON. This is done in the experience editor and uses the same layout engine as regular Sitecore pages. This allows content authors to use the tools they are already familiar with and personalization is supported. Also analytics and tracking are working like a regular Sitecore page as the layout engine is used to render.
  3. xConnect Client API: the xConnect client API needs to be used to retrieve the previous customers’ interactions with Sitecore.
  4. Commerce 9 OData API: any data which resides in Sitecore Commerce can be retrieved using this API.

Integration with the Sitecore services

There are several options to call the Sitecore services mentioned above. They were called from AWS Lambda in our demo during Symposium but there are some other options too:

  1. AWS Lambda: this is AWS’ serverless computing platform. Here are some key considerations for hosting this in Lambda:
    – Relatively simple integration with Alexa. Alexa runs in AWS and integration with Lambda takes just a few clicks and there are many examples online.
    – Little effort required to include Alexa SDK which simplifies integration with Alexa
    – Most Sitecore developers are not familiar with Lambda and will need to spend some time getting up to speed
  2. Azure/on-premise: Alexa can call any restful endpoint so the integration layer can be hosted anywhere accessible by AWS so this can be hosted in Azure or your existing on-premise data center:
    – No need to get up to speed with a new platform
    – Will require more effort to integrate securely with Alexa

Alexa Skill Kit SDK

There is an Alexa Skill Kit SDK available which makes working with Alexa significantly easier. The SDK is available in Node.js, Java and Python. Getting started with the Node.js SDK is surprisingly simple for C# developers as the new version 2 of the SDK is using async/await and promises instead of the callback based style which was previously used. Below is a code sample which runs when the user performs a search in the Alexa Skill. There are a few things to note about this:

  • This uses the Item Service to perform the search. The query is built on line 9.
  • The call to execute and await the search query is on line 11 and the httpGet method is starting at line 31. This calls the Item Service.
  • Methods from the Alexa Skill Kit SDK are used extensively for example on lines 23-28 to send the output speech to Alexa.

const SearchIntentHandler = {
    canHandle(handlerInput) {
        return handlerInput.requestEnvelope.request.type === 'IntentRequest'
            && === 'SearchIntent';
    async handle(handlerInput) {
        const searchTerm = handlerInput.requestEnvelope.request.intent.slots.SearchTerm.value;

        const query = '/item/search?term=' + searchTerm;

        const response = await httpGet(query);

        var searchResult = "";
        var cnt = 0;

        for (var i = 0; i  {
        const request = http.request(options, (response) => {
            let returnData = '';

            if (response.statusCode = 300) {
                return reject(new Error(`${response.statusCode}: ${response.req.getHeader('host')} ${response.req.path}`));

            response.on('data', (chunk) => {
                returnData += chunk;

            response.on('end', () => {

            response.on('error', (error) => {

Alexa Skill Interaction Model

The focus on this blog post is on the Sitecore integration with Alexa but it is important to understand that there is some Alexa work as well, specifically setting up the interaction model. There are 3 main entities in the interaction model:

  • Intents: the intent defines what the user is trying to achieve. The code above is handling the search intent.
  • Utterances: these are phrases likely spoken by the user to invoke the intent. Most intents will have multiple utterances. In above example an utterance mapped to the search intent could be “please search for “
  • Custom slot types: slot types hold the values for phrases the user says, but cannot be part in the utterance. In above example the “search term” is an example of a slot type and Alexa will automatically populate it with the search team spoken by the user.

The interaction model is stored in json, below is the json from the search intent. More information about the interaction model can be found here.

  "name": "SearchIntent",
  "slots": [
      "name": "SearchTerm",
      "type": "AMAZON.SearchQuery"
  "samples": [
    "please search for {SearchTerm}",
    "search for {SearchTerm}",
    "what is {SearchTerm}"

Integrated Alexa with other channels

It is important to built an Alexa Skill which is integrated with your brand’s other channels. A user is not going to have a good voice experience with a disconnected Alexa skill as this skill is not able to leverage customer interaction information from other channels to deliver a relevant and personalized experience. It is also important to understand customers behavior across all channels to get a single view of the customer and to provide relevant content to each user.

With the customer’s permission Alexa can return the location of the customer. This can be used to provide more relevant location based content to the user. During our presentation we showed location based personalization with Sitecore and Alexa. The location cannot be used integrate between channels as Amazon does not allow use of the location to associate the user to a customer with the same address. Amazon can reject or suspend your skill if they find out this is being done. More information about the use of location can be found here

Account linking is the feature which should be used to connect Alexa with other channels. Account linking connects the identity of the Alexa user to an identity in a third party system through OAuth 2.0. Setting this up will be easier if the Sitecore solution runs on version 9 since this supports federated authentication. More information about account linking can be found here.


Sitecore 9 fix heartbeat.aspx

The heartbeat page is a useful page in Sitecore as it shows if Sitecore can connect to it’s databases. If so it will return a 200 status. It can be found at /sitecore/service/heartbeat.aspx and it can be a good practice to point the load balancer’s health check to this page. This will avoid that any traffic is send to a server which cannot connect to its backend database.

Sitecore 9 has introduced a number of new connectionstrings with xConnect and the heartbeat page will fail on these. This can be avoided by adding the new connectionstrings to the excluded connections so the heartbeat page will not return an error while Sitecore’s databases are online. Below is the value which can be used to get the heartbeat page to work in Sitecore 9.

<setting name=”Sitecore.Services.Heartbeat.ExcludeConnection” value=”LocalSqlServer| xconnect.collection| xconnect.collection.certificate| xdb.referencedata.client| xdb.referencedata.client.certificate| xdb.marketingautomation.reporting.client| xdb.marketingautomation.reporting.client.certificate| xdb.marketingautomation.operations.client| xdb.marketingautomation.operations.client.certificate|  EXM.CryptographicKey| EXM.AuthenticationKey| Session| sharedSession” />

Deploying Sitecore 9 in AWS RDS

Using RDS to host Sitecore databases can be a good option when you want to deploy Sitecore 9 in AWS. RDS is a database service so you do not need to setup and maintain VMs or SQL Server. However you might run into a few issues when trying to do so, which are related to contained database authentication.

Enabling contained database authentication

Sitecore 9 uses contained database authentication by default. This avoids needing to manage logins outside the database. However this is turned off by default in RDS and trying to enable it through SQL like below will throw an error saying you do not have permission to run the RECONFIGURE statement.

--this will not work in RDS
sp_configure 'contained database authentication', 1;

Instead you will have to go to the database instance’s parameter group and set enable contained database authentication, see screenshot below. The instance might need to be restarted for this change to take effect.

RDS enable contained database authentication

Fix errors with SIF

The Sitecore Installation Framework might throw some errors as well because some of the Sitecore web deploy packages (.scwdp) try to enable contained database authentication through the above SQL code. This can be fixed by:

  1. renaming the package to .zip
  2. unzipping
  3. remove SQL code
  4. zip again, make sure to keep original folder structure
  5. rename to .scwdp and deploy

How to fix “RedisConnectionException: No connection is available to service this operation” in Sitecore

Redis is a great choice for Sitecore’s shared session database. Sitecore has a good article which describes how to set this up, and links to this article to explain all options. I was running into issues when setting this up with my Azure Redis Cache which is using an access key. The “accessKey” attribute in the provider node was populated with the access key form the Azure portal. Initially i was seeing something like this in the log:

INFO  Connecting
INFO faulted: UnableToResolvePhysicalConnection on PING

Then the log would be full of errors like below:

ERROR GetItemFromSessionStore => StackExchange.Redis.RedisConnectionException: No connection is available to service this operation: EVAL
   at StackExchange.Redis.ConnectionMultiplexer.ExecuteSyncImpl[T](Message message, ResultProcessor`1 processor, ServerEndPoint server)
   at StackExchange.Redis.RedisBase.ExecuteSync[T](Message message, ResultProcessor`1 processor, ServerEndPoint server)
   at StackExchange.Redis.RedisDatabase.ScriptEvaluate(String script, RedisKey[] keys, RedisValue[] values, CommandFlags flags)
   at Sitecore.SessionProvider.Redis.StackExchangeClientConnection.c__DisplayClass12_0.b__0()
   at Sitecore.SessionProvider.Redis.StackExchangeClientConnection.RetryForScriptNotFound(Func`1 redisOperation)
   at Sitecore.SessionProvider.Redis.StackExchangeClientConnection.RetryLogic(Func`1 redisOperation)
   at Sitecore.SessionProvider.Redis.StackExchangeClientConnection.Eval(String script, String[] keyArgs, Object[] valueArgs)
   at Sitecore.SessionProvider.Redis.RedisConnectionWrapper.TryTakeWriteLockAndGetData(String sessionId, DateTime lockTime, Object& lockId, ISessionStateItemCollection& data, Int32& sessionTimeout)
   at Sitecore.SessionProvider.Redis.RedisSessionStateProvider.GetItemFromSessionStore(Boolean isWriteLockRequired, HttpContext context, String id, Boolean& locked, TimeSpan& lockAge, Object& lockId, SessionStateActions& actions)

The only way I was able to get this to work was by not putting the access key in the provider but instead specifying it in the connection string (in ConnectionStrings.config):

<add name="sharedSession" connectionString=",password=rediskey,ssl=True,abortConnect=False" />

Sitecore is now able to connect to Redis and all errors are gone from the log. Below lines from log file show the successful connect:

INFO  Connecting
INFO  Connect complete:

Include files in TDS package that are not in Visual Studio solution

A Sitecore solution is often deployed by installing packages that are build by TDS. A lot of information can be found about different options to include files in a TDS package as long as the files are included in the Visual Studio solution. However there are many valid reasons to exclude files from a solution, for example CSS or JavaScript files which are build by gulp or webpack. In these scenarios it is often better to keep these files outside Visual Studio so developers update the source files and do not accidentally update the build artifacts.

TDS File Replacements

File replacements is an often overlooked feature of TDS but they are powerful for including files build by external tools which you do not want to include in Visual Studio or source control. Below screenshot shows how to include all files that are in the /dist/scripts/mysite folder. Notice that both the source and target location are relative paths. This ensures the source and target location always point to the correct path, even if the solution gets build in a different path, for example on the build server. File replacements

Fix invalid dynamic placeholders after upgrading to Sitecore 9

Sitecore 9 supports Dynamic Placeholders OOTB and does no longer require the popular Dynamic Placeholder third party module. The format used by Sitecore for the dynamic placeholders is different than the format used by the Dynamic Placeholder module:

Old dynamic placeholder pattern: placeholderName_renderingId. Example:


Sitecore placeholder pattern: {placeholder key}-{rendering unique suffix}-{unique suffix within rendering}. Example:


You will have to update your presentation details for these differences otherwise the renderings will not be shown on the page.

Richard Seal already wrote a great blog post about how to upgrade this using SPE. This works well and also does a great job of explaining other tasks that need to be performed to move to Sitecore’s dynamic placeholders. However it doesn’t cover below 2 scenario’s:

  • Nested Dynamic placeholder: a rendering with a dynamic placeholder can contain another rendering with a dynamic placeholder.
  • Multilingual: a item can have dynamic placeholders in multiple language versions of the final layout.


I started with Martin Miles’ code which iterates through all the renderings and updates placeholders. From here the logic is updated to loop through each language version of every item. Below code updates every match of an old style dynamic placeholder so nested placeholders are taken care of appropriately:

bool requiresUpdate = false;

foreach (RenderingDefinition rendering in device.Renderings)
    if (!string.IsNullOrWhiteSpace(rendering.Placeholder))
        var newPlaceholder = rendering.Placeholder;
        foreach (Match match in Regex.Matches(newPlaceholder, PlaceholderRegex, RegexOptions.IgnoreCase))
            var renderingId = match.Value;
            var newRenderingId = "-{" + renderingId.ToUpper().Substring(1) + "}-0";

            newPlaceholder = newPlaceholder.Replace(match.Value, newRenderingId);

            requiresUpdate = true;

        result.Add(new KeyValuePair<string, string>(rendering.Placeholder, newPlaceholder));
        rendering.Placeholder = newPlaceholder;

if (requiresUpdate)
    string newXml = details.ToXml();

    using (new EditContext(currentItem))
        LayoutField.SetFieldValue(field, newXml);

Working Solution

The final working solution is uploaded to my Github and can be found here A few notes on solution:

  • Admin page is added at <sitecoreurl>/sitecore/admin/custom/migratedp.aspx
  • All content under /sitecore/content is updated, template standard values are not
  • Make sure to back up content before running this


Habitat Demo Group and Visual Studio 2017

Recently I had the privilege of attending a Sitecore Helix training. I’ve been using Visual Studio 2017 for a while now and had no trouble getting the Habitat solution running, all I had to do was update the buildToolsVersion to 15.0 in the gulp-config.js file and everything worked as expected.

Getting the Demo.Group solution running was a little bit harder. This solution is necessary for these exercises. There is no buildToolsVersion property in the gulp-config.js, instead version 14.0 is hardcoded in the gulpfile.js. I added the property in the gulp-config.js and used this property in the gulpfile.js instead of 14.0.

After this change it got a little further but still was not able to successfully run all the Gulp tasks. This time it gave me this error: “throw new PluginError(constants.PLUGIN_NAME, ‘No MSBuild Version was supplied!’); ” This stackexchange post has the answer to this issue. The Sitecore.Demo.Group solution uses an old version of gulp-msbuild, updating this to version 0.4.4 in the package.json resolved all remaining issues.


Sitecore use OAuth2 login with OWIN

As an experiment I wanted to see if it would be possible to use the social logins such as google with Sitecore using a similar approach as a plain MVC app. More details around doing this without Sitecore can be found here Notice that the code used in ASP .NET MVC relies on OWIN authentication middleware and ASP .NET Identity. This makes sense in ASP .NET, but we’ll have to reconsider this when integrating with Sitecore. A similar post using OWIN in Sitecore using Federated Authentication can be found here.

Sitecore and OWIN

Using OWIN with Sitecore makes sense, it is certainly possible to not use OWIN and rely on a custom implementation instead. There are some blog posts as well that will help you get started.

Given the security implications of getting a custom implementation slightly incorrect, it is highly recommended to use a proven solution like the OWIN middleware.

Additionally OWIN is widely used in regular ASP .NET applications. OWIN comes as a nuget package which makes it straightforward to update and take advantage of new features.

Sitecore and ASP .NET Identity

Using Sitecore with ASP .NET Identity does not make sense to me as Sitecore still uses ASP .NET membership. Using ASP .NET Identity would add another component that I could not see a use or benefit for, but please let me know in case anyone does. Some code in this post is from this post which describes how to use OWIN without ASP .NET Identity in ASP .NET MVC.

Configuring OWIN Middleware

Below code configures the OWIN middleware to use google authentication:

using Microsoft.Owin;
using Microsoft.Owin.Security;
using Microsoft.Owin.Security.Cookies;
using Microsoft.Owin.Security.Google;
using Owin;

namespace SitecoreOwinGoogle
    public partial class Startup
        private void ConfigureAuth(IAppBuilder app)
            var cookieOptions = new CookieAuthenticationOptions
                LoginPath = new PathString("/Login")



            app.UseGoogleAuthentication(new GoogleOAuth2AuthenticationOptions
                ClientId = "your client id",
                ClientSecret = "your client secret"

Notice in the usings that only OWIN is referenced, there are no ASP .NET Identity referenes added. ClientId and ClientSecret can be obtained from from Google Developers Console Never store passwords and other sensitive data in source code, for best practices see here

Login Through Google

In the OWIN middleware /Login is set as the login path. This can be set to a different path as well as long as there is code running when that path is hit to handle the login. I added a controller rendering here to transfer control to google:

public ActionResult Login(string returnUrl)
    return new ChallengeResult("Google",
      string.Format("/Login/ExternalLoginCallback?ReturnUrl={0}", returnUrl));

The ExternalLoginCallback will redirect the user to secure page that he was trying to navigate to before the OWIN middleware kicked in. It is important to run this code in the path specified in the redirectUri parameter on the ChallengeResult constructor, in this case “/Login/ExternalLoginCallback”.  Again I’m using a controller rendering for this.

public ActionResult ExternalLoginCallback(string returnUrl)
    return new RedirectResult(returnUrl);

I have used the same ChallengeResult class as ASP .NET MVC:

// Used for XSRF protection when adding external logins
private const string XsrfKey = "XsrfId";

internal class ChallengeResult : HttpUnauthorizedResult
    public ChallengeResult(string provider, string redirectUri)
        : this(provider, redirectUri, null)

    public ChallengeResult(string provider, string redirectUri, string userId)
        LoginProvider = provider;
        RedirectUri = redirectUri;
        UserId = userId;

    public string LoginProvider { get; set; }
    public string RedirectUri { get; set; }
    public string UserId { get; set; }

    public override void ExecuteResult(ControllerContext context)
        var properties = new AuthenticationProperties { RedirectUri = RedirectUri };
        if (UserId != null)
            properties.Dictionary[XsrfKey] = UserId;
        context.HttpContext.GetOwinContext().Authentication.Challenge(properties, LoginProvider);

Redirect back to Sitecore

After google completed validating the user it will redirect back to Sitecore. By default OWIN expects this at /signin-google. Here OWIN will set the cookie used for the CookieAuthentication. Make sure to configure this page as an authorized redirect URI in google’s console.

Sitecore will try to handle the request which is made to /signin-google, Sitecore should not touch this request and let OWIN handle it. The easiest way to achieve this is by adding this page to the IgnoreUrlPrefixes setting. From there OWIN will call the callback URL specified in the ChallengeResult and this will redirect back to page that is secured.

Securing pages

That is all for the OWIN and OAuth code. Now that this is in place a controller action method can be decorated with the Authorize attribute to trigger the authentication flow. Below diagram shows the end-to-end flow:

Authentication flow

Further considerations

As mentioned before this blog post is a start in using OWIN with OAuth2 in Sitecore. However there are many other items to explore:

  • Multisite support: perhaps you have a multisite solution and some sites need social logins and other sites need a different login method. OWIN supports branching the pipeline to allow for different configurations based on a condition e.g. hostname
  • Support different social provider: this blog post only works with google, but OWIN supports several different logins like Facebook, Twitter, Linkedin or Microsoft.
  • Logoff: this post only covers login, but it should be fairly straightforward to implement logoff in a similar fashion.
  • Sitecore Virtual Users: the authentication in this post is basic, either you are successfully logged in from google or you are not. Most real world applications are more complicated and different users have different permissions. In these cases it can be helpful to create a Sitecore virtual user and assign Sitecore roles.
  • OAuth2 scope: there is a scope parameter which supports retrieving additional information about the user from google. The users will have to accept this first on the consent screen when they use google’s system to log in.


This post showed how to set up OWIN with Sitecore and OAuth2. Using OWIN significantly simplified working with OAuth2 and google. There are a number of additional considerations that must be taken into account before using this in a production scenario.

Sitecore namespace issues

Since I ran into this silly issue a couple of times I decided to dig into it a little bit and write a post about it. As developers we like to structure our solutions and projects by applying consistent naming conventions. Most Sitecore projects use a naming convention like this prefix.Sitecore.description. Usually the prefix is something like a company name or a brand name, and the description is something that describes the project’s role in the solution. There can also be multiple prefixes and descriptions separated by a period. Looking at Habitat an example of description could be Feature.Accounts.

A popular approach is to keep project names, assembly names, folder structure and namespaces all in sync for clarity. If you go with this approach you will end up with a namespace like MyBrand.Sitecore.Features.Accounts. This is where things can get a little messy because “Sitecore” is in the namespace and this can conflict with references to Sitecore DLL’s. Consider below piece of code:

namespace MyBrand.Sitecore.Features.Accounts
    using Sitecore;

    public class Helper
        public string ReturnCurrentItemName()
            var item = Sitecore.Context.Item;

            return item.Name;

This code will create below compile error:

Error CS0234 The type or namespace name ‘Context’ does not exist in the namespace ‘MyBrand.Sitecore’ (are you missing an assembly reference?)


The problem here is how namespace resolution works for nested namespaces, more details can be found in the C# language specification here. As the compile error suggests it is looking for the Context object in our class instead of in Sitecore in the root scope. The good news is that there are at least 3 different ways to solve this:

1. Avoid using anything before “Sitecore” in namespace

The same code will compile just fine when “Sitecore” is the first part of the namespace, see line 1. This is the easiest solution if changing the namespace is not a problem.

namespace Sitecore.Features.Accounts
    using Sitecore;

    public class Helper
        public string ReturnCurrentItemName()
            var item = Sitecore.Context.Item;

            return item.Name;

2. Use namespace alias

This is my least favorite way to solve this but it also seems to be the most common solution. The Sitecore namespace from the Sitecore DLL can be declared as an alias and then used to reference:

using RealSitecore = Sitecore;

namespace MyBrand.Sitecore.Features.Accounts
    public class Helper
        public string ReturnCurrentItemName()
            var item = RealSitecore.Context.Item;

            return item.Name;

3. Use global namespace alias

Instead of making up a random name for Sitecore as in the last solution, it feels a lot cleaner to use the global namespace alias to tell the compiler to look in the global namespace instead:

namespace MyBrand.Sitecore.Features.Accounts
    using Sitecore;

    public class Helper
        public string ReturnCurrentItemName()
            var item = global::Sitecore.Context.Item;

            return item.Name;


As long as there is no problem changing the namespace to start with “Sitecore” then option 1 is the best choice. If for whatever reason that is not an option then go with using the global namespace alias as described in option 3.

Set Rendering Parameters in Conditional Rendering

Sitecore has a set “Set Parameters” conditional rendering rule which sets the rendering parameters as the name implies. This rule has some limitations:

  1. It will remove all existing parameters
  2. User will have to know the querystring syntax to add the correct keys and values (e.g. parameter1=value1&parameter2=value2)

The second limitation can be resolved by educating the users to use correct syntax, but there is no option to resolve the first one. There are many legitimate scenarios where you would want to set some rendering parameters and either add some more based on a condition or overwrite the value for a particular parameter.

To support this scenario I created a custom conditional rendering rule to do this:

  1. If there is already a parameter and this is not specified in the conditional rendering rule, then leave it as is.
  2. If there is already a parameter, and the same is also set in the conditional rendering rule, then overwrite it with the value from conditional rendering rule.
  3. If the parameter is only in the conditional rendering rule, add it.

I used below code for my custom action:

using Sitecore.Diagnostics;
using Sitecore.Rules.Actions;
using Sitecore.Rules.ConditionalRenderings;
using System.Linq;

namespace Jeroen.Rules.ConditionalRendering
    public class MergeParameterAction<T> : RuleAction<T> where T : ConditionalRenderingsRuleContext
        public string Name { get; set; }

        public string Value { get; set; }

        public override void Apply(T ruleContext)
            Assert.ArgumentNotNull(ruleContext, "ruleContext");

            //grab the existing parameters
            var parameters = Sitecore.Web.WebUtil.ParseUrlParameters(ruleContext.Reference.Settings.Parameters);

            //parameter already there, overwrite
            if (parameters.AllKeys.Contains(Name))
                parameters[Name] = Value;
            //add new parameter
                parameters.Add(Name, Value);

            //add updated parameters back
            ruleContext.Reference.Settings.Parameters =
                string.Join("&", parameters.AllKeys.SelectMany(
                    parameters.GetValues, (n, v) => string.Format("{0}={1}", n, v)));

Below screenshot shows how to add the action:


Now the rule is available in Sitecore and ready to use. You can use the action multiple times in case you need to set multiple parameters as shown here. Now the additional parameters will be set and existing parameters will be kept, there is also no need for the user to remember the syntax, he can just click the name/value pair in the rule editor!