---
title: Integrate Optimizely Content Marketing Platform with CMS 13
slug: cms-13/docs/integrate-cmp-with-cms-13
createdAt: 2026-10-23T16:00:00.000Z
---

Integrate Optimizely Content Marketing Platform (CMP) with Optimizely Content Management System (CMS 13) to plan, create, review, and publish web content as part of a CMP task. Marketing managers work in CMP to create CMS pages from structured content, track their progress, and publish them. CMS editors work on the same pages in CMS and use CMP assets without copying them between systems.

Use the integration to run web content through the same CMP campaign workflow as your other channels. Structured content and assets stay in CMP, so teams do not maintain copies of them in CMS.

The integration builds on external content in CMS. For details on connected content, content type mappings, and property mappings, see [Integrate external content sources with CMS](https://docs.optimizely.com/cms-13/docs/integrate-external-content-sources-with-cms). Unlike other external content sources, you do not configure CMP through Optimizely Connect Platform (OCP). Instead, you install the integration package in CMS 13 and connect it to CMP with an integration in CMP.

## How the integration works

The integration connects a CMP task with one or more CMS content items:

- **Create CMS content from CMP** – A CMP user creates a CMS page from a structured content item in a task, using a CMS blueprint. CMS creates the page at the selected location and adds it to the task.
- **Add existing CMS content to a CMP task** – A CMS user adds content they are working on to a CMP task.
- **Use CMP assets in CMS** – A CMS user connects assets that belong to the CMP task to CMS content.
- **Preview, review, and publish from CMP** – The CMP task shows a live preview of each linked CMS content item. CMP users review and publish the content from the task.

Each product remains the source of truth for its own data:

- **CMP** – Tasks and workflows, Digital Asset Management (DAM) assets, and structured (omnichannel) content.
- **CMS** – Content items, compositions, and channel-specific properties.

## Before you begin

Complete the following before you install the integration:

- **Upgrade to CMS 13.7.0 or later** – Creating CMS content from CMP requires CMS 13.7.0 or later.
- **Configure the DAM integration** – Install the DAM integration package and connect CMP to CMS by indexing CMP assets into Optimizely Graph. See [Configure the DAM asset picker for CMS 13](https://docs.optimizely.com/cms-13/docs/configure-dam-asset-picker-cms13).
- **Get CMP API credentials** – You need the client ID and secret of a CMP API app. In CMP, go to **Settings** > **Apps & Webhooks**. You can reuse the app you created for the DAM integration.
- **Get administrator access** – You need administrator access in CMS 13 to set access rights, and in CMP to add integrations.

## Install the integration package

A developer installs the integration package and registers its services in the CMS 13 site.

1. Add the package references to the site's `.csproj` file. Keep every CMS package on the same version.

   ```xml
   <PropertyGroup>
     <CmsVersion>13.7.0</CmsVersion>
   </PropertyGroup>

   <ItemGroup>
     <PackageReference Include="EPiServer.CMS" Version="$(CmsVersion)" />
     <PackageReference Include="EPiServer.Cms.DamIntegration.UI" Version="$(CmsVersion)" />
     <PackageReference Include="Optimizely.Graph.Cms" Version="$(CmsVersion)" />
     <PackageReference Include="EPiServer.Cms.CmpIntegration" Version="$(CmsVersion)" />
   </ItemGroup>
   ```

   `EPiServer.CMS` includes the CMS REST API and its OAuth endpoints, which CMP calls to create and publish content. You do not need another package for that connection.
2. Register the services in `Startup.cs`. Add the CMS REST API with OAuth endpoints, DAM, Optimizely Graph, and the CMP integration.

   ```csharp
   using EPiServer.DependencyInjection;
   using Optimizely.Cms.DependencyInjection;
   using Optimizely.Cms.Service.V1.Authentication;
   using Optimizely.Graph.DependencyInjection;

   // ...

   if (_webHostingEnvironment.IsDevelopment())
   {
       services.Configure<CmsServiceOauthOptions>(o => o.AddDevelopmentSigningCredentials());
   }

   services
       // ...
       .AddCmsUI()
       .AddOptimizelyCmsServiceV1().AddOauthEndpoints();

   services
       .AddContentGraph()
       .AddDamUI()
       .AddCmpIntegration();
   ```

## Configure the integration

Add the integration settings to `appsettings.json`. Replace the placeholder values with your own.

```json
{
  "Optimizely": {
    "Cms": {
      "CmpIntegration": {
        "ModuleEnabled": true,
        "CmpTaskUrl": "https://cmp.optimizely.com/cloud/taskv3/"
      },
      "Service": {
        "Oauth": {
          "Clients": [
            { "ClientId": "CMS_API_CLIENT_ID", "ClientSecret": "CMS_API_CLIENT_SECRET" }
          ]
        }
      }
    },
    "CmpTasks": {
      "Client": {
        "TokenUrl": "https://accounts.cmp.optimizely.com/o/oauth2/v1/token",
        "ApiUrl": "https://api.cmp.optimizely.com/v3/",
        "ClientId": "CMP_APP_CLIENT_ID",
        "ClientSecret": "CMP_APP_CLIENT_SECRET",
        "UseHmacAuthentication": false
      }
    }
  }
}
```

The following table describes each setting.

| Setting                                                  | Required | Description                                                                                                                                                                        |
| -------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Optimizely:Cms:CmpIntegration:ModuleEnabled`            | Yes      | Set to `true`. The default is `false`, which hides the CMP options in CMS and makes the CMP endpoints return a `404` error.                                                        |
| `Optimizely:Cms:CmpIntegration:CmpTaskUrl`               | No       | The base URL for links that open a task in CMP. The default is `https://cmp.optimizely.com/cloud/taskv3/`.                                                                         |
| `Optimizely:Cms:Service:Oauth:Clients`                   | Yes      | The OAuth client that CMP uses to call CMS. Choose any client ID and a strong secret.                                                                                              |
| `Optimizely:CmpTasks:Client:ClientId` and `ClientSecret` | Yes      | The client ID and secret of your CMP API app. If you reuse the app from the DAM integration (`Optimizely:Cmp:Client`), you must still enter the values here.                       |
| `Optimizely:CmpTasks:Client:UseHmacAuthentication`       | Yes      | Set to `false`. The default is `true`, which signs requests with a hash-based message authentication code (HMAC) instead of requesting an OAuth token with the client credentials. |
| `Optimizely:CmpTasks:Client:TokenUrl` and `ApiUrl`       | No       | The CMP token and API endpoints. The defaults point to CMP production.                                                                                                             |

On Optimizely Digital Experience Platform (DXP) or Azure App Service, enter the settings as app settings with double underscores, for example, `Optimizely__Cms__CmpIntegration__ModuleEnabled` and `Optimizely__Cms__Service__Oauth__Clients__0__ClientId`.

Restart the site after you change the settings.

:::hint{type="warning"}
**Important**
Do not commit client secrets to source control. For local development, store them in user secrets or in an `appsettings.Development.json` file that is excluded from source control.
:::

## Enable the integration

The integration connects CMP and CMS 13 in both directions:

- **CMS to CMP** – CMS calls the CMP API to list tasks and add content to them. It uses the CMP API app in `Optimizely:CmpTasks:Client`.
- **CMP to CMS** – CMP calls the CMS API to create and publish content. It uses the OAuth client in `Optimizely:Cms:Service:Oauth:Clients`.

After you add the integration in CMP, your CMS 13 site displays as a channel in CMP. CMS editors then see **Add to task** in the CMS editing UI.

### Give the OAuth client access rights

CMP uses the OAuth client to browse the CMS content tree, list blueprints, create pages, and publish content. The client needs the following access rights:

- **Read** – Browse the content tree when a CMP user selects a location, and create content there.
- **Create** – Create pages.
- **Publish** – Publish the content in a task.
- **Administer** – Publish without reference validation. CMP skips reference validation when it publishes, and CMS allows that only with **Administer** access rights.

The client does not need **Change** or **Delete** access rights.

Set the access rights in the following places:

- **Start page** – Give the client all four access rights on the start page of each site that CMP creates content in or publishes to. Do not set them on the root, so the client only has access to the content CMP works with. Pages under the start page inherit the access rights. If a branch has its own access rights, add the client there too.
- **Pages that editors add from CMS** – Editors can add pages from anywhere in CMS to a task. CMP can publish a task only if the client has **Publish** and **Administer** access rights on every page in it.
- **Blueprints folder** – Give the client **Read** access rights on the **Blueprints** folder. The folder is under the root, not the start page, and does not inherit access rights. Without **Read** access rights, the **Blueprint** list in CMP is empty and CMP cannot create pages.

To set the access rights:

1. Open the access rights for the content in CMS 13, for example, your start page.
2. Search for the client ID. OAuth clients are listed under **Applications**.
3. Select the access rights for the client and save.
4. Check that CMS accepts the client. A `200` response that contains an `access_token` means that the client works.

   ```bash
   curl -u CMS_API_CLIENT_ID:CMS_API_CLIENT_SECRET -d grant_type=client_credentials https://CMS_HOST/_cms/v1/oauth/token
   ```

### Configure token signing

The CMS API signs its OAuth tokens with a key. The key depends on where the site runs:

- **Local development** – The `AddDevelopmentSigningCredentials()` line in `Startup.cs` creates a key. The key changes every time the site restarts, so tokens issued before a restart stop working.
- **DXP** – CMS uses the platform's `oidc-signing` certificate automatically.
- **Other hosting** – Add a signing key in code through `CmsServiceOauthOptions.SigningCredentials`.

### Add the Optimizely CMS integration in CMP

Add an Optimizely CMS integration in CMP to connect CMP to your CMS 13 site.

1. Go to **Settings** > **Integrations** in CMP.
2. Select the **Website, CMS & Feed** tab.
3. Click **Add** > **Optimizely CMS**.
4. Define the following. All fields are required.
   - **Display Name** – The name CMP users see for the channel, for example, *Stride.com (Production)*.
   - **CMS Site URL** – The host URL of your CMS 13 site.
   - **CMS Type** – Select **PaaS**.
   - **API Key (OAuth Client ID)** – The client ID from `Optimizely:Cms:Service:Oauth:Clients`.
   - **API Secret (OAuth Client Secret)** – The client secret from `Optimizely:Cms:Service:Oauth:Clients`.
5. Click **Save**.

## Prepare content types and blueprints

CMP users create CMS pages from structured content in a task. A CMS administrator sets this up by connecting CMP structured content types to CMS and mapping them to CMS content types. The administrator then creates blueprints for those content types.

### Prepare structured content types in CMP

A structured content type defines the fields that CMP users fill in for a piece of content in a task. CMP also calls structured content *omnichannel content*. Use an existing structured content type, or create one if you do not have a suitable type. Content types created in the CMP UI or with the CMP API work with the integration.

To create a structured content type, see [Create content types, components, and fields](https://docs.optimizely.com/content-marketing-platform/docs/edit-content-with-omnichannel-authoring#create-content-types-components-and-fields) in the CMP documentation. To create content types with the CMP API, see [Content type versions](https://docs.optimizely.com/content-marketing-platform/docs/content-type-versions).

### Connect CMP structured content types to CMS

CMS reads CMP structured content from Optimizely Graph. Before you map a CMP structured content type, connect it to CMS with **Connect from Graph**. You use the same process as for other external content sources. See [Connect from Graph types](https://docs.optimizely.com/cms-13/docs/advanced-content-types#connect-from-graph-types).

### Map CMP content types to CMS content types

Map each CMP structured content type to the CMS content type you want to create from it. Mappings are many-to-many, so you can map a CMP content type to more than one CMS content type, and the reverse. You use the same mapping process as other external content sources. See [Create content type mappings and map properties](https://docs.optimizely.com/cms-13/docs/integrate-external-content-sources-with-cms#step-3-create-content-type-mappings-and-map-proper).

### Create blueprints for mapped content types

CMP users create CMS pages from blueprints. After a CMP user selects a parent location, CMP lists only blueprints that meet the following conditions:

- The blueprint's content type has a mapping for the selected structured content type.
- The blueprint's content type is allowed as a child of the selected location.
- The OAuth client has access rights to create content of the blueprint's content type.

Create at least one blueprint for each mapped content type. See [Blueprints](https://docs.optimizely.com/cms-13/docs/blueprints) and [Manage blueprints](https://docs.optimizely.com/cms-13/docs/manage-blueprints).

## Create CMS content from a CMP task

CMP users create CMS pages from the **Content** tab of a CMP task.

### Create a page

Create a CMS page from a structured content item in a CMP task.

1. Open the task in CMP and go to the **Content** tab.
2. Select **More** > **Add to Channel** on the structured content item. The **Create CMS Page** window displays.
3. Define the following. All fields are required.
   - **CMS channel** – The CMS channel to create the page in, for example, **Stride.com (Production)**.
   - **Locale** – The language of the page. Select a language that is enabled in CMS 13.
   - **Parent location in CMS** – Where to create the page in the CMS content tree. **Selected location** shows the path of the page you select.
   - **Blueprint** – The blueprint to create the page from.
4. Click **Create page**.

CMS creates the page as a draft from the blueprint, in the selected locale and parent location. CMS connects the page to the structured content and adds it to the task. The **Content** tab then shows a live preview of the page.

CMS does not copy the structured content into the page. It reads the values from the connected CMP structured content. When you update the structured content in CMP, the page displays the new values automatically.

## Add existing CMS content to a CMP task

CMS editors can add pages, shared blocks, and other assets they are working on to a CMP task.

1. Open the content in CMS 13.
2. Select **More** > **Add to task**. The **Add to Task** window displays.
3. Search for the task by name, select it, and click **Add to Task**. Completed and archived CMP tasks are not listed.

CMS displays **Part of task:** *task name* on the content, with a link to the task. The content also displays on the task's **Content** tab in CMP.

A content item can belong to only one active CMP task. After the task is complete or the content is published, editors can add a new draft to another task.

If the content is part of a CMS project, CMS adds a separate draft of the content to the task. The project and the task each keep their own draft.

Editors cannot add content that is scheduled for publishing to a task, because scheduled content is already approved for publishing. **Add to task** is unavailable for that content.

### Remove content from a task

Remove content from a CMP task in CMS 13.

1. Open the content in CMS 13.
2. Select **More** > **Remove from task**.

The content stays in CMS, but it is no longer part of the CMP task.

## Use CMP assets in CMS content

For content in a CMP task, editors can connect CMS properties to assets from the task or the CMP Library. For content that is not part of a task, **DAM (CMP)** shows only Library assets.

1. Open the page in CMS 13 and select the block or element to edit, for example, a **Hero** block.
2. Select **More** > **Connect Content**.
3. Select **DAM (CMP)** under **Locations**.
4. Select the asset and click **Connect Content**.

The connected properties display a link icon and are read-only in CMS, because their values come from CMP.

Files attached to a CMP task are work in progress and are not in the CMP Library yet. When CMP publishes the CMS content, it copies the task assets into the Library. CMS then updates its references to point to the Library assets. Editors do not see a change in CMS.

## Preview, review, and publish from CMP

The **Content** tab of a CMP task shows a live preview of each CMS content item in the task. The preview updates as editors change the content in CMS.

Content in a CMP task can be published only from the task. In CMS, **Publish** and **Schedule for Publish** are not available for that content. When the content is ready, CMS editors select **Ready to Publish**.

When CMS content is added to a task, CMP adds the matching CMS channel to the task's **Publishing** tab. The **Publishing** tab shows which content is selected for publishing, and to which channel.

To publish the content, click **Mark Task Complete** in CMP. CMP then asks CMS to publish the content, using the OAuth client you added to the Optimizely CMS integration. Follow the publishing progress on the **Publishing** tab.

CMS validates all content in the task before it publishes any of it. If any content item fails validation, CMS publishes none of the task content.

After CMP publishes it, the content behaves like any other published content in CMS. Editors can create new versions of it as usual. For CMS publishing in general, see Control the publishing process.

:::hint{type="info"}
**Note**
CMP cannot bypass the publishing rules in CMS. If an approval sequence applies to the content, CMS does not publish it until a CMS user approves it. CMS also publishes the content only if the OAuth client has **Publish** access rights on it.
:::

## Troubleshoot the integration

The following problems are common, with their causes:

- **Add to task does not display in the content menu** – `Optimizely:Cms:CmpIntegration:ModuleEnabled` is not set to `true`.
- **Add to task is unavailable for a content item** – The content is scheduled for publishing.
- **The Add to Task window fails to load tasks** – `Optimizely:CmpTasks:Client:ClientId` or `ClientSecret` is missing or incorrect.
- **The Part of task link opens the wrong CMP environment** – `Optimizely:Cms:CmpIntegration:CmpTaskUrl` does not match your CMP environment.
- **The Blueprint list in CMP is empty** – The OAuth client does not have **Read** access rights on the **Blueprints** folder.

## Limitations of the integration

The following features are not part of the integration:

- Creating translations of existing pages from CMP.
- Creating blocks from CMP. CMP users can create only pages.
- Scheduled publishing. CMS publishes the content when a CMP user marks the task complete.
