Alexa and Sitecore Integration using OData and XConnect

Introduction

In this series of blog posts - we will take a whirlwind tour of how to create an Alexa skill to integrate with Sitecore. The skill will connect with Sitecore's OData Item Service to query content. In later posts we will also be recording Contacts and Events with XConnect. In this post - we will start with the basics.

The Proof of Concept

In true Blue Peter style - here's one I made earlier. I have created items representing dogs based on the Dog template in Sitecore. The Dog template has fields for description, celebrity (famous example) and personality. I will be querying by these fields.


Template Fields

Now - querying content via Alexa (sorry about the shaky video!)





Enabling the OData Item Service

With the release of Sitecore 9 - there is now a new OData Item Service (OIS) that allows us to query and retrieve content using the OData protocol. The OData Item Service is part of the Sitecore.Services.Client framework that enables developers to expose content and entities via APIs. It is just one of the varied ways in which Sitecore can be made "headless". It is also important to remember that OIS is read-only so you cannot import or update items as you can through other APIs.

In order to use OIS - we first need to enable access. This is done by setting up an OData API Key item in the Core database under /sitecore/system/settings/services/API Keys.




The settings that you need to specify are:
  • Database - this is the content database from which content will be queried and retrieved ie.. master or web.
  • CORS Origin - this is a semicolon delimited list of CORS domains that are allowed to access your content. I have specified * but you may choose to be more selective.
  • Allowed Controlers - this is a semicolon delimited list of controllers that are allowed to use the API Key. For this example I have just used the built-in Sitecore.Content.Services.Controllers.ItemsController. However, this setting does seem to imply that you can write your own OData compliant controllers.
  • Impersonation User - this is effectively the user context under which content will be queried and retrieved. OIS can be accessed anonymously using the account associated with the Sitecore.Services.AnonymousUser configuration setting. However, we can override this setting by specifying the account we wish to use in the Impersonation User field.
That is literally all you need to get started with OIS. Before you can start querying - ensure that your content is published (if using web db) and that SOLR is running and your indexes are up-to-date.

OData - where for art thou!?

The OData requests we will be making are all GET requests where we call the Item controller and pass some query parameters as well as the API key. It is important to note that the API key can either be passed through as a query string parameter or as a HTTP header. The format of the requests is as follows:

https://[service root]/[resource path]?[query options]

In our examples the service root is http://sc9xp0.sc/sitecore/api/ssc/aggregate/content/ and our resource path starts with /Items as we are interested in querying and retrieving items. The query options we use depend on what we want to get back. Below are some examples of OData queries.

Get the Home item:

http://sc9xp0.sc/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')?sc_apikey={28EAA678-F822-4341-BC75-C1CFB0A95B92}

Get all items that are derived from the Dog template:

http://sc9xp0.sc/sitecore/api/ssc/aggregate/content/Items?sc_apikey={28EAA678-F822-4341-BC75-C1CFB0A95B92}&$filter=(TemplateName eq 'Dog')

Get a Dog item with a Celebrity field value of Marmaduke:

http://sc9xp0.sc/sitecore/api/ssc/aggregate/content/Items?sc_apikey={28EAA678-F822-4341-BC75-C1CFB0A95B92}&$filter=TemplateName eq 'Dog' and Fields/any(f: f/Name eq 'Celebrity' and f/Value eq 'Marmaduke')

As you can see it's fairly easy to understand the queries being carried out above. When you execute such queries you will get a JSON response back like below with zero or more items.

{
    "@odata.context": "http://sc9xp0.sc/sitecore/api/ssc/aggregate/content/$metadata#Items",
    "value": [
        {
            "Name": "Great Dane",
            "DisplayName": "",
            "Path": "/sitecore/content/Home/Dogs/Great Dane",
            "Language": "en",
            "Version": 1,
            "IsLatestVersion": true,
            "TemplateId": "01754839-d487-4135-8db3-c3357790506f",
            "TemplateName": "Dog",
            "Created": "2017-11-01T18:51:21Z",
            "Updated": "2017-11-01T18:55:00Z",
            "ParentId": "8939556c-4960-4283-b583-b155b4b5c67b",
            "Id": "14cc922e-93f0-41fe-91d7-d245442c9159",
            "Url": "http://sc9xp0.sc/sitecore/api/ssc/aggregate/content/Items('14cc922e-93f0-41fe-91d7-d245442c9159')"
        }
    ]
}

This data can then be consumed by a calling application - be it another controller or client application including a Alexa skill. The specifics Alexa skill will follow in another blog post. Below is an image of an actual request / response between Alexa and OIS.

Thanks for reading - I hope you found this technique useful. Feel free share this article and leave feedback.



Comments

Post a Comment

Popular posts from this blog

Alexa and Sitecore Integration - Part 3

Image
The Story So Far In the previous posts I've described how to enable and use the OData Item Service in Sitecore and also how to set up a Alexa skill. In this final part of the series on Alexa and Sitecore integration - we finally come to the point where we plug in the newest part of Sitecore 9 - namely XConnect. This will allow us to collect data about what is being searched for via our Alexa Skill. Therefore, we are able to glean useful insights into user behavior and use the collected data to personalise content. Connecting the X's If you've read enough about XConnect, you will know that when we collect data, we  associate that data with a contact. Ideally we also try to identify the contact. So far ,we have not really discussed how we know who the user is. This is not really obvious for voice driven experiences as it is for web driven interfaces. For example, to identify a web user - a developer can force them to register or login and identify them with cookies.
Read more

Getting Up and Running with Sitecore 9

Image
This post serves to get you up and running quickly on a local instance of the newly released Sitecore 9. If you don't feel like reading the whole thing - use the links below to jump to the section that interests you. Prerequistes SQL Database Configuration SOLR Setup Install SIF and Sitecore Fundamentals Install XConnect and Sitecore Post-Install Steps Conclusion As Sitecore enthusiasts will no doubt be aware, Sitecore 9 was released recently and comes with a host of new features. I could probably go into some depth about these but will leave it to you to read the lowdown from the one-and-only JammyKam . The biggest change is XConnect which separates out Xdb related functions into a separate layer  enabling collection of analytics data from a wider variety of sources such as mobile apps, IOT sensors, third party apps etc. More information on XConnect can be found here . Another big change (no doubt influenced by XConnect) that you will face when downloading Sitecore
Read more

Introducing Helix DNA

In this post - I'm going to be introducing you to something I've been tinkering with for some time now. I like to call it Helix DNA (Dot Net Accelerator) and Double Helix. These two modules are my twist on creating Helix solutions from scratch. My experiments build on and bring together  strands  of techniques used previously by luminaries such as Akshay Sura and Mark Duiker. So a big thanks to them for the insights - I hope you like my take on it. Ultimately - I would like to release my experiments to the community but am keen to see what you make of this post and what the demand is for such a tool. Have I come too late to the Helix party? ;) TL;DR If you are the impatient type - you can jump to 2:48 for a demo of Helix DNA and 13:48 for Double Helix. You may also wish to use full screen mode when watching - or use a magnifying glass ;) So what is Helix DNA? Helix DNA (Dot Net Accelerator) is a Powershell module that uses EnvDTE tools within Visual Studio to pro
Read more