Disclaimer: This website requires JavaScript to function properly. Some features may not work as expected. Please enable JavaScript in your browser settings for the best experience.

Dev GuideAPI ReferenceChangelog
Dev GuideAPI ReferenceUser GuideLegal TermsDev CommunityOptimizely AcademySubmit a ticketLog In
Dev Guide

CMP Content Repository

Describes the Optimizely Content Marketing Platform Content Repository structure.

A Content Repository is a system that stores and hosts content and defines the structure of content.

You determine how the content is finally delivered to the consumer and let customers choose the media of their choice.

Content Repository is like a decoupled (or headless) CMS with the following added benefits:

  • Stored content with metadata that is accessible by an API
  • A workflow for creating content production
  • Integrated campaign planning
  • Integrated content from Optimizely Digital Asset Management (DAM) with collections for distribution of content
  • Integration with CRM and marketing automation to analyze content with ROI
  • Infrastructure to publish and distribute content
  • A preview for marketers while keeping the flexibility of not imposing it on the users of structured content. The preview is dynamically created, which is especially useful for legal approval.

Entities in the Asset Service

The Asset Service indexes content assets for previewing, searching, and listing structured content. Assets are made from the following entities:

  • An instance is an organization or creative management platform (CMP).
  • A Content Type is the definition of structured content. Content is an instance of a content type.
  • Structured content contains fields that define the metadata of the content. When you create structured content in the Assets Service, you can change the content directly and independently in the Content Repository. Changed data is re-indexed.
  • A field can be a single value or an ordered list of values. You can specify default field values (except the Content Type reference).

The Instance, Content Type and Content entities have the following fields associated with them:

  • Instance – (also known as Organization, CMP Instance)
    • Instance GUID
    • Name
  • Content Type – (also known as Content Blueprint, Content Model, Content Schema, Content Template)
    • Name
    • Source – Optional. Denotes the source of where the content type originates. If the source is set, those content types are not editable from within CMS to support content types controlled by other systems. For example, AEM, Sitecore, or CMP's predefined content types.
    • Source ID – Optional. Denotes the ID of the content type from which it is being imported.
    • Source Metadata – Freeform text field to store any meta-data to be used by the downstream system.
    • Instance GUID – Foreign key to Instance.
    • Thumbnail GUID – GUID of the thumbnail in the file server, similar to how attachment and asset upload work. This can represent what the content type could look like.
    • Content Type GUID – Must be unique across content types because it is used in reference.
    • Is Component? – Boolean that controls whether to list this content type in structured content creation in the Task & Content tab and whether you can add the template. You should not add templates to Components. With this prototype, you cannot create a component from a task because when a component is created from a task, it does not show up in the library. However, when a component is embedded in a non-component content type, the component gets an embedded behavior experience in the task's structured content editor.
    • Is Disabled? – Boolean that controls whether the content type is retired. A content type is not deleted because of the complexity of content created and used from a content type. When disabled, the content type is not listed for editing or content creation.
    • Versions[] – Ordered list of versions.
      • Version GUID – Generated GUID.
      • Create At
      • Created By – User GUID.
      • Is Latest?
      • Expected Locales – Array locale strings in the form of en_US.
      • FieldDefinitions
        • Name
        • Source ID – Optional. Denotes the ID of the field from which it is being imported.
      • Source Metadata – Freeform text field to store any meta-data to be used by the downstream system.
      • Type – One of Text, Rich Text, Number, Date and time, Location, Boolean, URL, JSON Object, Choice, Library Asset, Content Type Reference.
      • Is List – Flag to signify whether this is a list field.
      • Is required – For list, it would mean at least one item is required.
      • Needs Internationalization
    • Templates – (also known as Layout, Format) An ordered list of templates with a default blank template added at creation. The list cannot be empty.
      • Template GUID – Generated GUID.
      • Name
      • Description
      • Source ID – Optional. Denotes the ID of the template from which it is being imported.
      • Source Metadata – Freeform text field to store any meta-data to be used by the downstream system.
      • HTML Template
    • Description – Note about the content type.
  • Content – (also known as Structured Content)
    • Content GUID – generated GUID
    • Title
    • Content Type GUID
    • Instance
    • Is Reusable – Especially useful for Components; if is Private is false, it can be used as Shared Component and referred to by other Content.
    • Is Expired? – Gives delete-like capability for content in Content Repository. Structured Content can be deleted from the library, but at that point, it should be expired from the content repository. A CMS-only component can be expired from CMS view. Expired content is accessible in the Vault of Content Repository
    • Content Type Field Definition Version GUID – Foreign key to Content Type's Field Definition's specific version
    • Template – The link to one of the templates in a content type
    • Versions – Ordered list of versions
      • Field Version GUID – Generated GUID
      • Name – Optional. Name content to create a milestone around creating content; for example, session end milestone in case of auto-save.
      • Create At
      • Created By – User GUID
      • Generated Previews: Dict(Preview name: str, (GCP Mime-Type, GCP Content Data)) – Preview generated for content's specific version through API
      • Is Latest?
      • Dict (key, Dict(Locale, FieldValue[]) – Array of values keyed against locale and then by field key. Locale will default to the system default of en_US. It must match its type (see more on this below). If list size is 1, it is a single value rather than a list.

📘

Note

Content Repository versions field definitions in a content type and field values in a structured content. Each version is unique and cannot be changed.

Field types for the back end

You can configure a field to be required or optional, list or singular, or need internationalization.

  • Text Field – Supports minimum and maximum length configuration and can add a pattern to validate the string against.
  • Rich Text Field – Not supported in Content Repository. However, Contentful supports this field to let Quill and TinyMCE features to be configured. For example, headings h1 and h2 are not allowed, but h3 and h4 are allowed, and embedding images is allowed or not allowed, and so on.
  • Boolean
  • Datetime – Minimum date and maximum date (configurable).
  • Number – Minimum number and maximum number (configurable).
  • Library Asset – values: article , image , video , raw_file , structured_content

You can configure the type of asset and select multiple types. For example, a field can specify that a field can have image or video as its value.

  • Content Type Reference – Specify one or more types of content to embed or link.
    • You can configure embed-only to be reused. If you allow reuse from the content type, you should be able to mark it as one-time in the task details of the page so the content cannot be reused.
    • You can configure link-only to enable embedded editing.
  • Choice – values: Display option , Tag , Radio , Dropdown. Options are defined as part of the type.
  • URL
  • Location
  • JSON – Provides flexibility to submit random values to be used by downstream systems.

📘

Note

Media (Image, Video) is intentionally left out because it creates confusion between which image ends up in the library versus in the CMS. For the Library Asset type field, you can upload an image, video or file, which you can automatically add back to the task.

Core field definitions

Every field definition has the following common attributes (regardless of type).

  • key – Required. A unique key for identifying the field.
  • name – Required. Name of the field.
  • is_required – Required. Whether the field is required.
  • need_internationalization – Required. Determines the need for internationalization. (This is not used for now.)
  • is_list – Required. Specifies single value or multiple values.
  • min_list_length – Optional. If multiple, specify the minimum number of values.
  • max_list_length – Optional. If multiple, specify the maximum number of values.
  • field_type – Optional. Enter the name of the field.
  • order_index – Optional. Field's order index; see Ordering fields.
  • source_id – Optional. Source ID; see External content types.
  • source_metadata – Optional. Source metadata; see External content types.
  • editor_metadata – Optional. Field editor metadata; see Field editor metadata.
  • help_text – Optional. An informatory help text that describes the field.

Ordering fields

You can control the order in which fields are rendered when content is being created using the order_index attribute. If you do not specify some fields in order_index, those fields are rendered in an unpredictable order, followed by those specified in ascending order.

The order_index attribute is available in content type and FieldValue to retain the order in which values are entered in the list field.

Field Editor Metadata

You can customize the field value editor in the following ways:

  • Integer versus decimal for Number Field
  • Date Only instead of Date Time
  • Date or format to be used in the datetime editor (that is, mm/dd/yyyy versus dd/mm/yyyy or AM/PM versus 24-hr time format)

Web page content type

A system content type called Web page has the following common fields:

  • SEO keywords
  • SEO metadata
  • URL slug
  • Analytics pixel – The task details page automatically detects locales as they are added and generates a unique pixel per locale. You cannot edit the pixel.

Any other content type that wants these common fields can directly associate them.

Internationalization

You can create structured content from the Task Details page such that a single asset contains multiple locales. However, each locale-specific article is published independently. Statistics are gathered independently; each shows in the library independently (with lineage). For example, if Article A is published in American English (en), French (fr), and Swedish (sv), there are three separate assets: Article_A_en, Article_A_fr, and Article_A_sv.

Changes that trigger events from the Content Repository

  • Content Type
    • Content Type created
    • Content Type core info updated
    • Content Type version created
    • Content Type disabled
  • Structured Content
    • Content created
    • Content core info updated
    • Content version created
    • Content expired
    • Content affected
    • Preview requested
    • Preview generation started
    • Preview completed (value: complete, error, timeout)
    • Preview available

Most events are straightforward, but Content affected may have a shared component with other content. For example, shared component A could be part of structured content B and structured content C. If shared component A is changed, the Content Repository identifies the change to the initial component and each affected component.

Permissions for content

Role-based permissions determine whether you can create, update, or delete a component. Structured content inherits permission from the asset.

Integrate CMP Content Repository with CMS

You can use the API to create a content type and template, but you cannot modify these content types to avoid conflict and merge issues. External systems (such as SDL Tridion or AEM) can create and use their content types in CMP. The Source metadata and Source ID fields are set when the content type is created (you cannot update it afterward); the fields identify the content type as coming from external sources. Application users can view the definition and structure. They can create content from the external content type, and Source ID and Source metadata are available as optional fields at Field Definition and Template, which takes advantage of storing native CMS fields and template identifiers and additional freeform metadata.

Source metadata is also available at the content type level, which you can update after it is created. The Source metadata receives any string and has no format limitation, and the system populating them can control the metadata.

Endpoints

  • GET Instances
  • PUT to create or register an Instance
  • GET Content Types in context to an Instance; stretch goal – with filtering on Component
  • POST to Content Types to create content in context to an Instance
  • GET a Content Type with latest version in full
  • GET a Content Type with the latest version in full and expanded recursively for preview context
  • GET Content Type versions
  • GET a Content Type version
  • POST to a Content Type to update its core information
  • POST to Content Type versions to create a field definition version
  • GET Contents in context to an Instance filtered by Content Type, Component, Private Type and Content's title (full text) paginated
  • POST to Contents to create content
  • GET a Content with its latest version
  • GET a Content version
  • GET a specific Version of a Content
  • GET a Content with its nested content for preview context
  • GET a Content with its nested content for search indexing
  • POST to a Content to update its core information
  • POST to a Content's Versions to update it (Patch is supplied later on) with a new version
  • GET a Content Type's templates resource to list the templates for a content type
  • POST to a Content Type's templates resource to add a template to the content type
  • GET a Content Type's specific template (retrieves it)
  • PUT to a Content Type's template (updates it)
  • DELETE to a Content Type's Template (DELETES it)

Because the listing of structured content is limited to Assets for MVP, you will not have the delete endpoints. These endpoints are prefixed with v0 to allow for versioning of the Content Repository API.

Common HTTP response status codes across the endpoints:

  • 200 – For requests to GET endpoints
  • 201 – If your content was created for your POST request, the API returns the URI with the Location of the created content or content type
  • 202 – If your content type or content was updated for your PUT request
  • 404 – If there was no content type or content found in the referenced URI
  • 412 – Entity Tag supplied for PUT requests are not valid
  • 422 – If input JSON does not meet validation criteria
  • 500 – For any unexpected, back-end error from the Content Repository