---
title: Connect external content sources using GraphQL
slug: cms-saas/docs/connected-content-sources
docTags: 
createdAt: 2026-07-30T20:18:08.000Z
---

In Optimizely Content Management System (CMS), you can connect external content indexed in Optimizely Graph. This lets you reference and reuse external content in pages, experiences, and blocks without duplicating or synchronizing data manually.

When you connect to an Optimizely Graph schema, CMS creates a connected content type. Connected content types mirror the external schema but are read-only. Only a limited number of settings can be updated in CMS.

## Benefits

- **Editors** – Insert external content into CMS pages, experiences, and shared blocks. A link badge indicates when a content item is connected.
- **Administrators** – Decide which schemas are connected and how they map to CMS content types.
- **Developers** – Rely on a consistent, supported integration instead of building custom sync logic.

## Connect from Optimizely Graph

1. In **Admin > Content Types**, select **Create new\... > Connect from Graph**.

![](https://files.readme.io/315a241ea7d076b37f1022ea991f466a5a272ea7122352a9c6be4d669c284461-image.png)

If other external content source providers are available, they also appear in this menu. Learn more about how to Integrate external content sources with CMS (SaaS)

:::hint{type="info"}
**Note**
If other external content source providers are available, they also appear in this menu. Learn more about how to [Integrate external content sources with CMS (SaaS)](docId:0rH8xhLxvuDFjv6Hmputd).
:::

2. In the **Connect from Graph** window, update the following:
   - **Source** – Select the external source available in Graph.
   - **Schema** – Choose from the following:
     - **Available schemas** – Schemas that can be connected.
     - **Connected schemas** – Schemas already connected. Selecting one displays a link to the existing CMS content type.
     - If no schemas are available, the list is hidden.
   - **CMS base type** – Select from the supported base types: Page, Component, Media, Video, or Image. See [Content types](docId\:IIrc48HRxDZe6C7wiVBVT) for more information.
   - **Content ID** – Select the schema field that uniquely identifies items.
   - **Content name** – Select the schema field used as the display name.
   - Click **Connect**.

::Image[]{src="https://files.readme.io/158052b6e854b1f7edb292af2e3ef0479de8f7bc236a051ded28ab01fed71e0d-ManageContentSource1.png" size="40" alt="Connect from Graph" caption="Connect from Graph" isUploading="false" darkWidth="445" darkHeight="624" width="445" height="624" showCaption="true"}

## Validation and connection behavior

When you connect a schema from Optimizely Graph, CMS validates references and types to ensure they can be used safely.

### Reference validation

If a schema includes reference fields, CMS checks whether the referenced types are available and supported.

- If a referenced type is not connected as a content source, CMS shows a validation error and prevents the connection.
- If a referenced type exists but is not available in the same source, CMS cannot verify compatibility and blocks the connection.

### Skip validation

You can bypass validation by calling the API with the `skipValidation` option.

When you skip validation:

- If the referenced type exists but is not connected, CMS creates a generic reference using the closest supported contract.
- If the referenced type cannot be verified, CMS skips the reference field.
- If the referenced type is unsupported, CMS skips the reference field.

Skipping validation may result in incomplete or missing reference fields in CMS.

:::hint{type="info"}
**Note**
Skipping validation may result in incomplete or missing reference fields in CMS.
:::

## Map source and target content types

Mappings define how properties from one content type populate properties in another. You can create mappings between the following:

- A connected schema (source) and a CMS content type (target).
- Two CMS content types.

To configure a mapping

1. In the **Create Mappings**, select the source and target content types.
2. For each property on the target, select a matching property from the source.
   - A **target** content type is the content type in CMS to which data is mapped. Target properties are read-only and listed in order.
   - A **source** content type is the content type that provides values.
3. To reverse the direction, select **Swap Source and Target**.
4. Click **Create Mapping**.

::Image[]{src="https://files.readme.io/f813f19bd223ae7b139aa978e0b72300fa6c4565fe1c22a63c0eb5cad2c688c0-ManageContentSource2.png" size="50" alt="Mapping Content Types" caption="Mapping Content Types" isUploading="false" darkWidth="500" darkHeight="247" width="500" height="247" showCaption="true"}

Mappings can include scalar properties inside a block at one level of depth.

:::hint{type="info"}
**Note**
Mappings can include scalar properties inside a block at one level of depth.
:::

## Connected content types

When you connect a schema from Optimizely Graph, CMS creates a connected content type. Connected content types appear in the **Content Type** list together with regular CMS content types.

Connected content types are read-only in most areas because they mirror the schema from the external source. Administrators can update limited settings such as the following:

- **Properties**
  - Displays all properties defined in the schema.
  - All properties are read-only, but you can select a property to view its details.
  - A message confirms that the content type is connected to an Optimizely Graph schema.

![](https://files.readme.io/c85aca36184522fb593af7073ec6b3aa856f2a51b0b76d2497a814cc73a1e1b6-Properties.png)

- **Details**
  - Shows system identifiers and configuration.
  - All values are read-only.

![](https://files.readme.io/7b784aee1fa5e1d7de22139a70fbd740b0612063a6d5c37e1a6c1987e550ac9e-Details.png)

- **Settings**
  - **Name** and **Display name** are read-only.
  - You can update
    - **Content ID**
    - **Content Name**
    - **External edit URL**
    - **Sort index**
  - If the schema follows a global contract, only the **External edit URL** can be updated.

![](https://files.readme.io/cb9d6f99a6a7b22e33d56cd15ca0f66d76d14be5ba99483d10a8673fee4ca348-settings.png)

- **Mappings**
  - Create and manage mappings from this schema to CMS content types.
  - Connected types can only act as a source in a mapping.

![Mappings](https://files.readme.io/1343b5d8135982b3c024088a23708455f915175d08b40ae19be777a59c3ca5a0-image_2.png "Mappings")

- **Permissions**
  - Displays current permissions.
  - Read-only.

## Content references from Graph

Schemas in Optimizely Graph can include references between content items. CMS converts these references into content references that you can use in the same way as standard CMS references.

### How references are created

- If a referenced type is available in CMS, the reference is created as a typed content reference.
- If a referenced type is not fully available, CMS creates a generic reference when possible.

### Requirements

To be recognized as a content reference in CMS:

- The referenced type must follow a supported global contract.
- If the referenced type does not follow a supported contract, CMS cannot create a reference.

Behavior for unsupported references

- Unsupported references trigger a validation error during connection.
- If you skip validation, unsupported references are ignored and not created in CMS.

## Bind content in the Visual Builder

Editors can connect pages, experiences, or shared blocks to external data sources in the **Edit UI** when a mapping exists.

### Indicators

- **Link badge** – Appears next to the content title when the item is bound to a source.

![Link badge](https://files.readme.io/fd840a120e9ec70c3ab799c5eb05fee8a2ba602ff7f56556cca0be9ca1a258c6-Link_badge.png "Link badge")

### Context menu options

- **Connect content** – Available for unbound items when a mapping exists. Opens the Content Manager picker, filtered to show only compatible source types.

![Connect Content type](https://files.readme.io/3327b3ecca0d19403cba45593c31b640cb82aeaaa85b1562bd850fd4bdaeb460-connect_context.png "Connect Content type")

- **Replace** – Available for bound items. Lets you select a different source from the Content Manager picker.
- **Disconnect** – Available for bound items. Removes the connection to the source.

![Replace and disconect connected content type](https://files.readme.io/22ac714b79ad2a74504e5b9f1f3577f637f65d7658e837e6571c18a67c93079a-replace_disconect.png "Replace and disconect connected content type")

### Behavior of bound content

- Properties included in the mapping are read-only and display values from the source.
- Properties not included in the mapping remain editable in the **Edit** UI.
- If the mapping is updated to include additional properties, those properties automatically become read-only and display values from the source. In the following example, the *longString* is a connected content type, whereas the *longSting2* is a normal connected type.

![Behavior of bound content](https://files.readme.io/01ec421cf8dd33eaa5d8a2ea5380b312228306ac7aa326ffc112f2f4f7d15666-behaviour.png "Behavior of bound content")

## Delete a connected content type

You can delete manually connected content types in the same way you delete a regular CMS content type. System-managed content sources that are automatically created from contracts cannot be deleted through the UI or API. Deleting removes the connected type from CMS, but it does not affect the original schema in Optimizely Graph.

![Delete content type](https://files.readme.io/1811b82021a80c9d505ae0f9a708dab7b632eb0923c5d239c20fcf0134188387-delete.png "Delete content type")

## Use connected content types in selectors

When you configure **Allowed content types** or **Restricted content types** for a property, connected content types are available alongside regular CMS content types.

![connected content types](https://files.readme.io/1ceca7c3bc6cb646717519d5722612416c1b8b571cf22a50556592c84504d03f-connected_content_type.png "connected content types")

The selectors now behave consistently with the **Reference** type selector.

- You can pick from regular CMS content types.
- You can also pick from all top-level connected content types (those directly associated with a schema).

This enables you to reference content from external sources in the same way you reference CMS content.