Integrate Optimizely Content Marketing Platform with CMS 13
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. 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.
- 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.
- Add the package references to the site's .csproj file. Keep every CMS package on the same version.
<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.
- Register the services in Startup.cs. Add the CMS REST API with OAuth endpoints, DAM, Optimizely Graph, and the CMP integration.
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.
{
"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.
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:
- Open the access rights for the content in CMS 13, for example, your start page.
- Search for the client ID. OAuth clients are listed under Applications.
- Select the access rights for the client and save.
- Check that CMS accepts the client. A 200 response that contains an access_token means that the client works.
curl -u CMS_API_CLIENT_ID:CMS_API_CLIENT_SECRET -d grant_type=client_credentials https://CMS_HOST/_cms/v1/oauth/tokenConfigure 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.
- Go to Settings > Integrations in CMP.
- Select the Website, CMS & Feed tab.
- Click Add > Optimizely CMS.
- 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.
- 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 in the CMP documentation. To create content types with the CMP API, see 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.
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.
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 and 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.
- Open the task in CMP and go to the Content tab.
- Select More > Add to Channel on the structured content item. The Create CMS Page window displays.
- 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.
- 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.
- Open the content in CMS 13.
- Select More > Add to task. The Add to Task window displays.
- 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.
- Open the content in CMS 13.
- 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.
- Open the page in CMS 13 and select the block or element to edit, for example, a Hero block.
- Select More > Connect Content.
- Select DAM (CMP) under Locations.
- 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.
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.