CMP-CMS Integration Architecture
Why a separate integration layer exists
Section titled “Why a separate integration layer exists”CMP and CMS serve different roles. CMP is where content teams plan, write, and approve content. CMS is where that content is structured, rendered, and delivered to visitors. Connecting these two systems requires more than a simple export — it requires a mapping layer that understands both content models and translates between them.
The integration architecture handles this translation. It ensures that content produced in CMP arrives in CMS with the right structure, in the right location, with assets properly transferred.
Architecture overview
Section titled “Architecture overview”The CMP-CMS integration consists of three layers:
Connection layer
Section titled “Connection layer”The connection layer establishes authenticated communication between CMP and CMS. It handles:
- Authentication — OAuth-based service-to-service credentials that authorize CMP to create and update content in CMS
- Endpoint discovery — CMP queries the CMS API to learn available content types, properties, and media capabilities
- Health monitoring — Continuous checks that verify the CMS instance is reachable and the credentials remain valid
The connection is configured once by an administrator and shared across all users who publish from CMP.
Mapping layer
Section titled “Mapping layer”The mapping layer defines how CMP content structures translate to CMS content types. This is the most configuration-intensive part of the integration.
| CMP concept | CMS equivalent | Mapping requirement |
|---|---|---|
| Content type (e.g., “Blog Post”) | Page type (e.g., BlogPage) | One-to-one type mapping |
| Text fields (title, body, summary) | String and XhtmlString properties | Field-level mapping with format conversion |
| Image references | ContentReference to media items | Asset transfer and reference linking |
| Tags and categories | Category or tag properties | Taxonomy alignment |
| Publish date | Scheduled publish date | Date field mapping |
| Author information | Author property or metadata | Optional mapping |
Each content type pair requires its own mapping configuration. A “Blog Post” in CMP might map to BlogPage in CMS, while a “Product Update” maps to NewsPage.
Transfer layer
Section titled “Transfer layer”The transfer layer handles the actual movement of data when content is published:
- Content serialization — CMP packages the content item’s fields according to the configured mapping
- Asset upload — Referenced images and files are uploaded to the CMS media library if they do not already exist
- Content creation or update — CMP creates a new draft page in CMS, or updates an existing one if the content was previously published
- Reference resolution — Internal links between content items are resolved to CMS content references
- Status callback — CMS confirms receipt, and CMP updates the content item’s status
Data flow: publish operation
Section titled “Data flow: publish operation”When a user triggers “Publish to CMS” on an approved content item, the following sequence executes:
- CMP validates that the content item has a valid type mapping for the target CMS
- CMP resolves the target location in the CMS content tree (specified by the user or defaulted from the mapping configuration)
- Assets referenced in the content are checked against the CMS media library — new assets are uploaded, existing ones are reused
- CMP constructs the CMS content payload using the field mapping, converting rich text formats, resolving asset references, and applying default values for unmapped required fields
- CMP calls the CMS content API to create a draft or update an existing page
- CMS returns the created content reference, which CMP stores for future update operations
- CMP transitions the content item’s status to reflect the published state
CMS SaaS vs CMS PaaS integration differences
Section titled “CMS SaaS vs CMS PaaS integration differences”The integration works with both CMS platforms, but with different characteristics:
| Aspect | CMS SaaS | CMS PaaS |
|---|---|---|
| API surface | Content Definitions API + Content Delivery API | Custom API endpoints via add-on |
| Authentication | OAuth 2.0 with Optimizely One identity | API key or custom auth |
| Content type discovery | Automatic via API | Manual configuration or custom connector |
| Asset handling | Direct upload to cloud media storage | Upload to configured blob storage |
| Bi-directional sync | Supported (changes in CMS reflect back to CMP) | One-way only (CMP to CMS) |
| Setup effort | Minimal — built-in connector | Moderate — requires connector installation |
Conflict resolution
Section titled “Conflict resolution”When content exists in both systems, conflicts can arise. The integration handles these scenarios:
- CMP update to existing CMS page — CMP creates a new draft version in CMS, preserving the published version. Editors review the draft before publishing.
- Concurrent edits — If someone edits the CMS page while CMP pushes an update, CMS creates a branch version. The editor resolves the conflict manually.
- Deleted CMS content — If a CMS page is deleted after being linked to CMP, the next publish from CMP creates a new page rather than failing.
- Schema drift — If the CMS content type changes (new required fields, removed properties), the mapping layer flags the mismatch during the next publish attempt.
Security and access control
Section titled “Security and access control”The integration respects both systems’ permission models:
- CMP users need the “Publish to CMS” permission in their CMP role to trigger publishing
- The service account connecting CMP to CMS has scoped permissions in CMS — typically limited to content creation in specific areas of the content tree
- Asset transfers use the CMS media permissions model — uploaded assets inherit the default permissions of the target media folder
- Audit logs in both systems record who initiated the publish and what was transferred
Monitoring the integration
Section titled “Monitoring the integration”Administrators can monitor integration health through:
- Connection status — Dashboard indicator showing whether CMP can reach CMS
- Publish log — Record of every publish operation with success/failure status and error details
- Mapping validation — Periodic checks that flag content type mappings broken by CMS schema changes
- Webhook notifications — Optional alerts for failed publish operations, sent to email or Slack