REST SDK and Sitecore

Sitecore is a popular .NET based Enterprise Content Management system that when coupled with Verint Community provides a powerful platform for customer engagement. Because they are built on the same underlying technology, the Rest SDK makes integrating the two systems together easier.

[toc]

Installation and Configuration

Since this is an SDK, there is an assumption that you have a Visual Studio solution that you are using to develop Sitecore components. The easiest way to start using the SDK is to install it into this solution using NuGet. For more detailed instructions on how to install, review the Rest SDK article's ""How to Get It" topic. This process will install the supporting files and references needed to begin configuring the SDK for first use.

Once installed, you need to decide which Host you wish to use. You should take some time to review the Hosts topic to understand what they are and how they work. The configuration of the SDK depends on the choice you make. Here is a quick overview of the 2 available hosts that may help you choose the best path to continue researching:

Default REST Host - This is by the far the most feature-rich of the 2 hosts. It also requires the most configuration, all of which is covered in more detail in the Default REST Host topic. This host is capable of:

Performing all the Basic Requests of the SDK
Optional Single Sign-On that automatically handles user creation and synchronization in the community
Url proxying- You can create a special code handler the allows you to replace the urls returned in REST with urls you define in Sitecore.
Multiple Host support if you needed to manage different hosts for different reasons, such as for multi-tenancy.

Client Credentials REST Host - If you just want to surface some information your Sitecore site, like a list of blogs or forum threads and don't need all the additional functionality, or you want more granular control over how everything works then this host may be appropriate. This host is the simplest of the hosts as it allows you to just make REST calls using Oauth and not have to worry about managing OAuth tokens or add additional complex configuration. With this host you can:

Perform all the Basic Requests of the SDK
Act as a single user or impersonate other users in the community

Default REST Host and Sitecore

Unlike the Client Credentials REST Host, the Default REST Host needs to be initialized and configured in code depending on the features you use. It is recommended that this all be done in the application start or as close to it as possible. One proven way to do this in Sitecore is to use a pipeline. Now if you do not wish to use any of the options that require code based configuration such as using local user accounts or url proxying, then you do not need to do this. The host will self initialize the first time you retrieve it. Here is an example of initializing the host in a pipeline:

using Sitecore;
using Sitecore.Pipelines;
using Telligent.Evolution.Extensibility.Rest.Version1;

namespace Telligent.Rest.SDK.Sitecore.Pipelines
{
    public class InitializeHost
    {
        public virtual void Process(PipelineArgs args)
        {
            Host.Get("default");
        }
    }
}

Then using the Sitecore configuration files you insert it into the <initialize /> pipeline:

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <pipelines>
      <initialize>
        <processor type="Telligent.Rest.SDK.Sitecore.Pipelines.InitializeHost, Telligent.SitecoreSDK" />
      </initialize>
    </pipelines>
  </sitecore>
</configuration>

Now that you have this in place, you can use this host reference to set up additional features described in the Default REST Host topic such as local user detection and url proxying.

If you choose to use Sitecore accounts as the basis for your community, you can use this pipeline to configure how the host gets your authenticated user:

using Sitecore;
using Sitecore.Pipelines;
using Telligent.Evolution.Extensibility.Rest.Version1;

namespace Telligent.Rest.SDK.Sitecore.Pipelines
{
    public class InitializeHost
    {
        public virtual void Process(PipelineArgs args)
        {
            Host.Get("default").ResolveLocalUser = (host, resolveArgs) =>
            {
                if (Context.User == null || !Context.User.IsAuthenticated)
                {
                    return null; 
                }
                return new LocalUser(Context.User.Name, Context.User.Profile.Email);
            };

            //If you do not wish to use domain accounts
            //Host.Get("default").ResolveLocalUser = (host, resolveArgs) =>
            //{
            //    if (Context.User == null || !Context.User.IsAuthenticated)
            //        return null;

            //    return new LocalUser(Context.User.LocalName, Context.User.Profile.Email);
            //};
        }
    }
}

For more information in this topic see the "Use Your Existing Accounts" topic in the Default REST Host article. Additionally, you can also add your delegates forUrl proxying.

using Sitecore;
using Sitecore.Pipelines;
using Telligent.Evolution.Extensibility.Rest.Version1;

namespace Telligent.Rest.SDK.Sitecore.Pipelines
{
    public class InitializeHost
    {
        public virtual void Process(PipelineArgs args)
        {
            var host = Host.Get("default");
            host.ResolveLocalUser = (host, resolveArgs) =>
            {
                if (Context.User == null || !Context.User.IsAuthenticated)
                {
                    return null; 
                }
                return new LocalUser(Context.User.Name, Context.User.Profile.Email);
            };
            
            host..GetRedirectUrl = (host, url, urlArgs) =>
            {
               //The url parameter is the you can use it to evaluate if you need to redirect it.
               //Return the Url you wish to redirect to
               return url;
            };
        }
    }
}

Using The SDK

Other than the above mentioned areas for the Default REST Host, you can use the SDK like you would in any .NET application. This includes writing special side code to do special non-interface tasks, or you can write code to power your ASPX pages or MVC powered views. You can learn more about the usage and configuration of the SDK by reading the [REST SDK]] topic and its sub topics.

Recommended