Key Concepts

Some key concepts can help you understand how to develop with Oracle Content Management as a headless CMS:

Content Model

Oracle Content Management is your universal content hub in the cloud, providing an API-first content management and delivery platform.

To learn more about Oracle Content Management, visit https://www.oracle.com/content-experience.

Oracle Content Management manages three types of content, as shown in the diagram below:

  • Sites—You can build sites in an easy-to-use, feature-rich WYSIWYG environment using content and assets managed in Oracle Content Management. See Building Sites with Oracle Content Management for further information.
  • Documents—This is content that’s mostly used for collaboration, syncing, or backup purposes. It will often be business content such as documents, spreadsheets, or presentations, but it can be any file type, including images and videos. See Collaborating on Documents with Oracle Content Management for further information.
  • Assets—This is content that’s typically used for content modeling, publishing, and delivery. It will often be media files (images or videos), but they can also be documents or structured content that includes text. In headless development, you’ll mostly be working with assets, so that’s what we’ll be focusing on here. See Assets for further details, and also Managing Assets with Oracle Content Management.

Description of content-model.png follows
Description of the illustration content-model.png

Note:

"Regular" (that is, non-asset) documents can easily be turned into assets if their business use changes. New, separate copies of these documents will then be created for use as assets.

Content authors and contributors typically manage and access sites, documents, and assets in the Oracle Content Management web interface, desktop app, or mobile apps. As a headless developer, you’ll primarily use the REST APIs—mostly the REST API for Content Delivery and REST API for Content Management—to access content programmatically for inclusion in applications or delivery to various publishing channels.


Description of main-sections-web-ui.png follows
Description of the illustration main-sections-web-ui.png

Videos

Oracle has partnered with Kaltura to provide built-in, advanced video management capabilities called Video Plus within Oracle Content Management.

This integration makes it easy to create, edit, and publish video content directly within Oracle Content Management, and then deliver that video content to any channel.

All video management, collaboration, and workflow are done within Oracle Content Management. Under the covers, though, the video content is converted on the Kaltura platform, and then delivered from Kaltura. This ensures that you can manage your videos as part of the central Oracle Content Management asset hub, include them as part of your sites and experiences, and deliver those videos in an optimized way to all your channels.

If you’re creating your site in Oracle Content Management using Site Builder, then Oracle offers out-of-the-box components that you can use to deliver the videos to your sites. However, with more and more people taking advantage of Oracle Content Management as a headless content management system, the site you’re building can be created using a tool or platform outside of Oracle Content Management. You can embed the video from Kaltura within any page and still take advantage of the Kaltura features in a way that’s more customized for your audience.

At a high level, you can embed a video from Kaltura in a number of ways:

  • Using the web browser’s default HTML5 video support
  • Using another custom video player
  • Using the Kaltura JavaScript player

Embed the Kaltura player

The example below shows how to embed the Kaltura player in your page and then pull or load the published video content from Oracle Content Management. The process is pretty straightforward:

  1. Obtain the configuration parameters for the video—partner ID, player ID (or user interface configuration ID), and entry ID for the video—through the REST API for Content Management.
  2. Add the JavaScript for the Kaltura player to your page.
  3. Pass the configuration parameters to the Kaltura player on your page.

Obtain the Configuration Parameters

Before loading the player JavaScript library, you need to know the following IDs:

  • Partner ID
  • Player ID (or UI configuration ID)
  • Entry ID of the item you want to include

If you have the ID for the video you want to embed, you can use the REST API for Content Management to extract all of this information.

If you don’t have the video ID, you can use the REST API for Content Management or REST API for Content Delivery (for published content). Alternatively, you can get that information from the Oracle Content Management web interface directly; for example, by looking at the API properties of the Video Plus asset.


Description of cec-mobile.png follows
Description of the illustration cec-mobile.png

Then use the REST API for Content Management to get the video:

GET http://{host}/content/management/api/v1.1/items/{item_ID}

This will return data in the following format (not all data values are shown):

{
    "id": "CONT4879B63407F3431487E694FF1E1616D7",
    "type": "DigitalAsset",
    "name": "Mobile.mp4",
    "description": "",
    "fields": {
        "metadata": {
            "width": "1920",
            "height": "1080"
        },
        "advancedVideoInfo": {
            "provider": "kaltura",
            "properties": {
                "duration": 58,
                "videoStripProperties": "n15,h168,w300",
                "extension": "mp4",
                "searchText": “Mobile.mp4 ",
                "name": "Mobile.mp4",
                "status": "READY",
                "entryId": "1_9ijq4y5e",
                "endpoint": "https://www.kaltura.com",
                "partner": {
                    "id": "2735841"
                },
                "player": {
                    "id": "46290582"
                }
            }
        },
        "renditions": [ . . . ],
        "mimeType": "video/mp4",
        "fileGroup": "AdvancedVideos",
        "version": "1",
        "fileType": "mp4"
    },
}
                "status": "READY",
                "entryId": "1_9ijq4y5e",
                "endpoint": "https://www.kaltura.com",
                "partner": {
                    "id": "2735841"
                },
                "player": {
                    "id": "46290582"
                }
            }
        },
        "renditions": [ . . . ],
        "mimeType": "video/mp4",
        "fileGroup": "AdvancedVideos",
        "version": "1",
        "fileType": "mp4"
    },
}

Note the entryID, partnerID, and playerID values that were returned (shown in bold above). You’ll use these values to configure the player later.

Add the Embed Code

Add the embed code for the Kaltura player, within the entryID, partnerID, and playerID specific to the Video Plus asset you want to embed:

  <div id="my-player" style="width: 640px;height: 360px"></div>
  
  <script type="text/javascript" src="http://cdnapisec.kaltura.com/p/{partnerID}/embedPlaykitJs/uiconf_id/{playerID}">
  </script>
  
  <script type="text/javascript">
  try {
    var config = {
        targetId: "my-player",
        provider: {
           partnerId: {partnerID},
           uiConfId: {playerID}
        }
    };
    var kalturaPlayer = KalturaPlayer.setup(config);
        kalturaPlayer.loadMedia({entryId: '{entryID}'});
  } catch (e) {
    console.error(e.message);
  }
  </script>

And that’s it. The playerID value is the player configuration for the Kaltura player, as defined for playback within Oracle Content Management. However, you can modify the settings for the Kaltura player and do something different than the Oracle Content Management default.

Learn More...

Content Versions

Changes to content in Oracle Content Management are tracked as revisions. This means Oracle Content Management maintains a snapshot, or version, of each update to an asset.

The content snapshots of an asset are readily available to the content author in the Properties panel on the Activity tab, as the following image shows.


Description of headless_content-versions_properties.png follows
Description of the illustration headless_content-versions_properties.png

Content authors can see content versions either for all languages or just for the currently selected asset (Current Language).

Please note the numbering of content versions, which follows a very specific format: {published version}.{local version}. For example, v1.002 means that this asset has been published at version 1 and two subsequent updates exist for this asset, but those changes have not yet been unpublished (local versions). If an asset was never published, its published version is 0.

When an asset is published, its published version number is set to the next number. For example, if an asset goes through updates marked v0.001, v0.002, and v0.003, and is then published, the new version for the current asset will be v1.000 (marked simply as v1). Subsequent numbering continues with v1.xxx as local updates are made to the asset (v1.001, v1.002, and so on).


Description of headless_content-versions_version-numbers.png follows
Description of the illustration headless_content-versions_version-numbers.png

Even though all content versions are retained in Oracle Content Management, only the current (latest) version is available for content management operations. This means that only the latest version of the asset can be approved or published or associated with other assets. Older versions exist for the purposes of tracking and review by content authors, not for actual use of that content.

Learn More...

Friendly URLs for Assets

Oftentimes an asset is all that’s needed to render a whole page, such as a blog post. In situations like that, it would be nice to have the URL of the web page contain the title of the blog.

Suppose I have a blog post titled “Morning Starts with Coffee”. I would want the URL of the page that shows this blog post to be something like https://..../blog-morning-starts-with-coffee.html. This is very easy to accomplish with Oracle Content Management because you can enable friendly URLs for content types.

Once friendly URLs are enabled for a content type, a new field is added to assets of that type. Furthermore, Oracle Content Management automatically populates the friendly URL field with the asset name. As soon as I create a blog asset, its "Friendly Item Name for URL"—also called slug in the API—shows the name of the asset (with some automatic character replacements for better URL handling).

Of course, you can change this friendly URL to anything you want. Oracle Content Management handles all the necessary validations to make sure it’s unique.


Description of friendly_urls-png.png follows
Description of the illustration friendly_urls-png.png

This slug field is now part of the asset’s data. When you get this asset (say, from a search list), you can fetch the slug field and use that in your client to construct the URL of a page.

More interestingly, Oracle Content Management provides a way to fetch the asset using just the slug value. For example, instead of accessing this blog asset with

https://.../content/published/api/v1.1/items/COREB6795E95BE27481690961D6657D5B70E?channelToken=83e8e3bc1f5f55f9b02a8183622589ad

you can use the slug in the URL:

https://.../content/published/api/v1.1/items/.by.slug/blog-morning-starts-with-coffee?channelToken=83e8e3bc1f5f55f9b02a8183622589ad

This means that if the slug of an asset is in the URL of a page, all that the client needs to do is grab that string and request the underlying asset by slug. This saves a round trip to look up or search for an asset with a slug and then fetch its assets.

It’s useful to note that every variation of the API that exists for an /items/{id} also exists for /items/.by.slug/{value}. These two APIs are therefore equivalent from the perspective of the content delivery API.

Learn More...