HomeDev guideRecipesAPI ReferenceGraphQL
Dev guideUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

CMS + CMP publishing experience

Describes how to set up the publishing experience between CMS and CMP.

πŸ‘

Beta

CMS + CMP is in beta. Apply on the Optimizely beta signup page or contact your Customer Success Manager.

Optimizely Content Management System (CMS) and Optimizely Content Marketing Platform (CMP) integrate for a seamless experience. This document describes how to set up the publishing experience by connecting CMP to CMS, and connecting CMS to CMP.

Install Orchestrate package into CMS

You are provided with an installable NuGet Package for your CMS site. These will be available on the NuGet feed as a package prior to general availability.

  1. Edit nuget.config in your project, in the same folder as your .csproj or .sln file.

    <configuration>
    <packageSources>
     <add key="CmpPublishing-beta" value="https://pkgs.dev.azure.com/EpiserverEngineering/netCore/_packaging/Kingfisher/nuget/v3/index.json"/>
    </packageSources>
    </configuration>
    
  2. Install package:

    dotnet add package EPiServer.CMS.OrchestrateIntegration --prerelease
    

This package installs all dependencies needed for the CMS + CMP Publishing Integration to operate.

πŸ“˜

Note

The beta version requires the latest CMS.Core packages, 12.14.0 or above, you might see this error when restoring the solution:

error NU1107: Version conflict detected for EPiServer.Framework. Install/reference EPiServer.Framework 12.14.0 directly to project orchestrate-packages to resolve this issue.
If you see the above error, install the latest version of these packages directly to the project:

dotnet add package EPiServer.CMS.AspNetCore.HtmlHelpers  
dotnet add package EPiServer.CMS.AspNetCore.TagHelpers

dotnet add package EPiServer.Hosting

Connect CMS to CMP

  1. In your CMP instance, go to your avatar > Integrations.

  2. Open the Website, CMS & Feed tab and click Add > Optimizely CMS 12 to add an integration. A CMS 12 form displays.

    CMS 12 form

    πŸ“˜

    Note

    The Client ID and the Client Secret are set inside of the app settings within CMS. They can be whatever you want them to be as long as CMP knows what those credentials are.

    a. Enter a Website Name.

    b. Enter a Website URL.

    c. Enter the Client ID.

    d. Enter the Client Secret.

    e. Click Save.

  3. Go to your avatar > Apps & Webhooks to set up an application that lets CMS communicate with CMP to save events and content that are changed in either product.

  4. Click Register App. The Apps & Webhooks screen displays.

  5. Open the Apps tab.

    the apps tab

    a. Enter a Name.
    b. (Optional) Add a description.
    c. Enter a Homepage URL for the CMS site that you are connecting to.
    d. Enter the Authorization Callback URL (using the same domain).
    e. Click Create App. The app displays in the app panel.

    newly created app

  6. Click the app you created. The app displays a Client ID and Client Secret you can use in the CMS settings.

    app details that show you the client id and client secret

Connect CMP to CMS

  1. In CMS, modify the following code block in appsettings.json.

    "Optimizely": {
      "Cms": {
        "Service": {
          "OauthClients": [
            {
              "ClientId": "cmp_publishing_integration",
              "ClientSecret": "a secret",
              "AllowActAs": true,
              "SigningKey": "If the site is not hosted by DXP, replace this with a 32-character string such as ABCDEFGHKLMANOPQABCDEFGHKLMANOPQ."
            }
          ]
        }
      },
      "Cmp": {
        "Client": {
          "ClientId": "Replace with CMP Client Id settings",
          "ClientSecret": "Replace with CMP Client Secret settings"
         }
      }
    }	
    
    • Cms:Service:OauthClients – Lets CMP connect to CMS and manage content.

      • ClientId – You should use cmp_publishing_integration (but you can use any ID you want).
      • ClientSecret – Your app's secret from CMP.
      • AllowActAs – If Opti ID is enabled, the integration acts as the user that is currently logged in, so that CMS and CMP know which authorized user is making changes, publishing content, or updating anything else in the CMS.
      • SigningKey – If you are not on Optimizely Digital Experience Platform (DXP), enter a 32-character signing key.
    • Cmp:Client – Lets CMS connect to CMP and provide real-time events and information when changes are made. Use the credentials generated when you created the app in CMP in the prior section.

      • ClientId – Use from CMP app.
      • ClientSecret – Use from CMP app.
  2. Add the following to your startup class to let the CMS editor load in CMP. It also changes how some site cookies work, but it is up to a developer to implement a content security policy for it.

    private readonly IWebHostEnvironment _webHostingEnvironment;
    private readonly IConfiguration _configuration;
    public Startup(IWebHostEnvironment webHostingEnvironment, IConfiguration configuration)
    {
      _webHostingEnvironment = webHostingEnvironment;
      _configuration = configuration; 
    }
    public void ConfigureServices(IServiceCollection services)
    {
      ...
      // Added this after .AddCms()
      services.AddCmsOrchestrateIntegration();
      //Enable anti-forgery to be iframe:d into CMP
      services.AddAntiforgery(options =>
        {
          options.Cookie.SameSite = SameSiteMode.None;
          options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
        });
      //To enable ASP.NET Identity to be iframe:d into CMP
      services.ConfigureApplicationCookie(options =>
        {
          options.Cookie.SameSite = SameSiteMode.None;
          options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
        });
      //To enable OptiID to be iframed into CMP 
      services.Configure<CookieAuthenticationOptions>(OptimizelyIdentityDefaults.CookieSchemeName, options =>
        {
          options.Cookie.SameSite = SameSiteMode.None;
          options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
        });
      if (_webHostingEnvironment.IsProduction())
        {
          services.AddCmsCloudPlatformSupport(_configuration);
        }
    }
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
      ...
      // NOTE! Add these before app.AddAuthorization()
      app.UseCors();
      app.UseCmsOrchestratePreviewLinks();
      ...
    }
    
    

Configure access rights

The configured client needs access to read and preview content. To configure access rights for Optimizely:Cms:Serice:OauthClients:0:ClientId, go to Admin > Access Rights in CMS. You should grant the following minimum level of access rights needed to integrate CMP and CMS.

  1. Grant access to the Root folder.
    1. Select the Root folder.
    2. Scroll down and click Add User/Group.
    3. Select the Client ID configured in appsettings.json.
    4. Assign Read permission to the Client ID.
    5. Save access rights.
  2. Grant access to your site Start folder.
    1. Select your Start folder.
    2. Scroll down and click Add User/Group.
    3. Select the Client ID configured in appsettings.json.
    4. Assign Read, Create, Change, Delete, and Publish permissions to the Client ID.
    5. Save access rights.

Set CMS destination folders in CMP

See Set CMS destination folders in CMP.

Enable support for CMP analytics in CMS (optional)

If you want CMP analytics in CMS, add CmpTrackingPixel to CMS content types that should support tracking; the property is automatically assigned for content published from CMP.

The following procedure uses the CMS Alloy sample site. You must customize the procedure for your implementation of templates in CMS.

  1. Add a reference to the analytics JavaScript, the URL for a specific account can be retrieved from CMP. In Alloy, add it to _Root.layout.

    <script async src="//analytics.newscred.com/analytics_<CMP_ID>.js"></script>
    
  2. Add the property to page types that should support analytics. In Alloy, add the property to SitePageData.cs to have it on all page types.

    [Display(GroupName = SystemTabNames.Settings, Order = 400)]  
    [CultureSpecific]  
    public virtual string CmpTrackingPixel { get; set; }
    
  3. Add the tracking pixel to the templates. In Alloy, add the tracking pixel into _Root.layout to make it render on all pages.

    @if (Model.CurrentPage.CmpTrackingPixel != null)  
    {  
      <img src="@Model.CurrentPage.CmpTrackingPixel" />  
    }