A quickstart guide to Oracle Content and Experience as a headless CMS for developers
April 3, 2020Oracle Content and Experience (OCE), also known as Oracle CX Content (CX for “customer experience”), has been gaining attention in recent years as a compelling alternative to many of the content management system (CMS) solutions on the market today. (For full disclosure, I currently lead product strategy for the OCE developer experience at my employer Oracle.) With features that run the gamut from traditional CMS needs like layout management, site templating, and in-context preview to more unusual characteristics like its capabilities surrounding smart content and document storage, OCE is an enterprise-grade CMS and intelligent content platform well-positioned to serve a variety of content management needs.
One aspect of OCE’s feature set that has witnessed comparatively less attention is its headless CMS capabilities. As a refresher, a headless CMS is a content management system that is leveraged primarily as a content server for consumption by other applications, whether they are other websites developed in technologies like JavaScript or digital experiences reflecting the ongoing explosion in digital channels. OCE contains two web services driven by application programming interfaces (APIs) that allow arbitrary read and write queries of a variety of resources under OCE’s purview. Moreover, beyond OCE’s increasingly API-first trappings, the team is working diligently to build and open-source a variety of samples (or reference applications) to aid developers working with OCE APIs.
In this article, I offer a quickstart guide for developers angling for more information about OCE and how they can leverage the Content Delivery and Content Management APIs available in OCE’s headless CMS capabilities to support entire digital ecosystems with a single source of truth for content. This quickstart guide aims to support you through the process of acquiring an Oracle Cloud account, provisioning an instance of Oracle Content and Experience, and finally issuing your first request—all with the goal of getting you to productivity as quickly as possible.
Registering for Oracle Cloud
By registering an Oracle Cloud account, you can access the 30-day trial that Oracle Content and Experience provides for all new users. This free trial of OCE offers thirty days of free access and USD 300 in free credits (known in Oracle parlance as Universal Credits). If you already have an Oracle Cloud account, you can skip to the next section, entitled “Provisioning an instance of Oracle Content and Experience.”
Selecting an account name and home region
First, navigate to Oracle.com and click Try Oracle Cloud Free Tier followed by Start for free. Insert your e-mail address and country or territory in the appropriate fields, and click Next to proceed.
On the following screen, provide a Cloud Account Name, which you’ll use to access your Oracle Cloud account, and a Home Region, which can be selected from a list of Oracle’s data regions. You will then be asked to provide contact information, including your mobile phone number for account verification.
Providing payment information
Oracle Cloud requires trial users to provide payment information such as credit card details, but you will not be charged unless you choose to upgrade the account to a paid subscription. After you provide payment information, you will be asked to agree to the terms and conditions of the Oracle Cloud Services Agreement.
Finally, Oracle Cloud will proceed to create an account for you. This may take up to fifteen minutes, and a confirmation of your account creation will be sent to the e-mail address you provided, where you can activate your Oracle Cloud account.
Provisioning an instance of Oracle Content and Experience
Note: Oracle has a visual step-by-step explainer that covers how to provision OCE on Oracle Cloud Infrastructure (OCI).
Now, we need to create an instance of Oracle Content and Experience. If you already have an Oracle Content and Experience instance, you can skip to the next section, entitled “Adding a content model, content, and channel.”
Log in to your Oracle Cloud account. Note that your Cloud Account Name is distinct from the user name and password. You can think of the Cloud Account Name as representing the same of your organization and your Oracle Cloud user name and password as representing you as an individual user. Navigate to the Infrastructure Dashboard.
Open the hamburger menu in the upper lefthand corner and, under Solutions and Platform, hover over Application Integration and select Content and Experience.
Choosing a storage compartment
In Oracle Cloud, compartments are used to organize cloud resources for a variety of purposes, including isolation, access, and billing. Due to security reasons, it is highly recommended to create and use a new storage compartment rather than using the existing root storage compartment.
Creating your OCE instance
Now, click Create Instance to create your new service instance of OCE.
Provide a name for the instance and an optional description before clicking Create.
It will take some time for the instance to be created, but the instance list page will refresh automatically to keep you updated on the status of the instance’s creation. Once the provisioning has completed, you can click the instance name to access its details.
Finally, once the instance has been created, you can click Open Instance to navigate to the web interface of the provisioned instance. Now, we’re ready to do some content modeling, add some content, and publish it to a channel!
Adding a content model, content, and a channel
By default, every new instance of Oracle Content and Experience comes empty, with an empty content model and no created content. In order to use OCE as a headless CMS, we need to supply a content model, create content, and publish it to a channel. If you already have content published to a channel, you can skip to the next section, entitled “Configuring OCE as a headless CMS.”
Open your instance. Note that in previous screenshots the instance of OCE we created is named XalcoInstance01.
Creating a content model
First, we need to create a content model that contains particular content types and associated fields. Content editors will choose a content type each time they wish to create a new content item, and responses that developers ingest in consumers will also adhere to the created content schema.
Navigate to Content in the left sidebar and select Content Types from the select list in the header. Then, click Create in the upper righthand corner. The Create Content Type modal (as visible in the screenshot below) will ask you to provide a name for your content type and an optional description.
For the purposes of getting started quickly, we only need a simple content type. Let’s call it NewsArticle. Give the NewsArticle content type four fields (each reflecting a distinct field type) with the following values filled in on the Settings step of the Text Settings modal (we’ll skip Appearance for now):
The Author field is a required single-value Text field having the display name Author and the machine name newsarticle_author.
The Date field is a required single-value Date field having the display name Date and the machine name newsarticle_date.
The Content field is a required single-value Large Text field having the display name Content and the machine name newsarticle_content.
The Image field is a required single-value Image field having the display name Image and the machine name newsarticle_image.
The screenshot below shows our settings for the Author field as an example. Depending on the field type, the structure of the form will change.
Now that we have our content type created, we can now turn to creating an asset repository that will allow us to create content items adhering to that content type.
Creating a publishing channel
In Oracle Content and Experience, a channel represents ranges of digital experiences that need to be served content by the headless CMS. You can also think of channels as containers for configuration and policies related to publishing content. Though channels can be public or secure depending on requirements, we’ll focus only on public channels here.
Suppose you have a React application that needs to consume OCE content. By creating a channel with a name like JavaScript, you can publish content to the JavaScript channel and make it available to any JavaScript application, including your React application, that may need to consume that content. Instead of using channels to represent sets of digital experiences, you can also designate channels for individual experiences (e.g. channels named AugmentedReality or DigitalSignage).
Navigate to Content and select Publishing Channels from the select list in the header. You will see an empty list without any channels created. In the upper righthand corner, click Create to create a new channel. Give the channel the name QuickstartChannel for the purposes of this quickstart tutorial and keep the access public. Click Save to create the channel.
Creating an asset repository
In Oracle Content and Experience, an asset repository is essentially a large “bucket” that houses all of the content items (known in OCE as assets; see next section) an organization needs to work with.
Navigate to Content and select Repositories from the select list in the header. You will see an empty list without any asset repositories created. In the upper righthand corner, click Create to create a new asset repository. Give the asset repository the name QuickstartRepo for the purposes of this quickstart tutorial.
Choose the NewsArticle content type under the Content Types label to indicate to OCE that assets of type NewsArticle can be created in the QuickstartRepo asset repository.
Finally, choose the QuickstartChannel channel under the Publishing Channels label to indicate to OCE that content in the QuickstartRepo repository can be published to the QuickstartChannel channel.
For now, we can leave everything else untouched and click Save.
Creating a content item (asset)
In Oracle Content and Experience, an asset is the atomic unit of managed content and adheres to a particular content type. Each content item is an asset. For developers coming from other CMS ecosystems, assets in OCE are most similar to what many CMSs call entities or records.
To create your first asset, click Assets in the left sidebar and click Create in the upper righthand corner, where a select list showing NewsArticle will be displayed. Select NewsArticle.
In the Create Content Item form, insert “My First News Article” as the Name under Content Item Properties and insert filler content into Content Item Data Fields, which contains the fields we defined for the NewsArticle content type. Then, in the Channels sidebar, click Add and select QuickstartChannel to identify it as the channel to which we’ll be publishing.
Publishing content assets to a channel
Now, in order to make the content we have just created available to the QuickstartChannel channel, we need to publish both assets we have just created to the channel, including both the NewsArticle content item and the image associated with it.
Navigate to Assets in the left sidebar, where you’ll find both of these assets available as unpublished assets. Select them both and click Publish in the action links that appear above the selected assets.
On the following Validation Results screen, verify that the assets you want to publish to the QuickstartChannel channel are represented. Click Publish in the upper righthand corner to verify. This will publish both assets to the channel, now making it available for public consumption.
Configuring OCE as a headless CMS
In order to enable Oracle Content and Experience as a headless CMS, we need to configure cross-origin resource sharing (CORS) for security reasons and acquire an API access token for our publishing channel. If you already have CORS configured and an API access token at hand, you can skip to the next section, entitled “Configuring OCE as a headless CMS.”
Note also that for the purposes of providing a base URL of your CMS back end, the instance URL is the domain name in your URL bar that ends with oraclecloud.com.
Configuring cross-origin resource sharing (CORS)
Cross-origin resource sharing (CORS) prevents unauthorized requests from overloading your API and causing distributed denial-of-service (DDoS) attacks. To configure CORS, navigate to System in the left sidebar and click Security in the select list in the header. If you already have domains ready for your consumer applications, you can insert them into the Front Channel CORS Origins field, which allows access to content through Oracle Content and Experience’s REST APIs and embedded components.
As you can see in the screenshot above, we have configured CORS to allow for requests originating from the https://example.com domain. To include additional domains allowed access to OCE’s REST APIs, insert a comma-separated list of domains (no quotation marks or other delimiters necessary). Now, any domains we have indicated to OCE as CORS-enabled will be able to issue requests successfully to OCE’s APIs.
Acquiring and refreshing API access tokens
As we saw earlier in this quickstart guide, assets in Oracle Content and Experience must be published to a channel in order for that content to be made available to other consumers such as mobile or JavaScript applications. Because channels can have differentiated sets of published assets, each channel provides its own unique API access token, which must be included in every request in order to target an individual channel.
Navigate to Content in the left sidebar and click Publishing Channels in the select list in the header. Select the QuickstartChannel channel from the list of channels. Under the API Information header, you will see two fields whose values can be copied to the clipboard: Channel ID and Channel Token. To refresh your channel’s API access token, click Refresh to the right of the Channel Token.
Note: You can also acquire your channel API access token programmatically by issuing a request to the OCE Content Management API.
Issuing your first request to OCE
Now, our next step is to issue our first request to Oracle Content and Experience to determine that our APIs are configured properly. Recall that the instance URL is simply the domain at which your OCE instance resides, adhering to the following format, where
{instance_name}{cloud_account_name}https://{instance_name}-{cloud_account_name}.cec.ocp.oraclecloud.comCopy your instance URL and keep it handy, as this is the domain against which you will be issuing every API request from your consumer applications. In the coming tests, we’ll be retrieving the NewsArticle asset we created earlier and published to the QuickstartChannel channel.
To acquire the identifier of your NewsArticle asset, which you will need to supply in a request to retrieve an individual asset with a
GET{asset_id}https://{instance_name}-{cloud_account_name}.cec.ocp.oraclecloud.com/documents/assets/view/{asset_id}Copy this
{asset_id}GET
In the next three sections, we will use three different approaches (Postman, cURL, and a typical XMLHttpRequest) to issue a request to retrieve a published item. The resource path takes the following format, with the added
channelToken{channel_token}https://{instance_name}-{cloud_account_name}.cec.ocp.oraclecloud.com/content/published/api/v1.1/items/{asset_id}?channelToken={channel_token}Without the
channelToken403 ForbiddenRetrieving content through Postman
One of the most ubiquitous developer tools for testing API requests is Postman, a free API client and desktop application. Postman provides a convenient user interface to form your request, including request headers and request body.
To test an API call from Postman, insert the following into the path for a new Postman
GETchannelTokenhttps://{instance_name}-{cloud_account_name}.cec.ocp.oraclecloud.com/content/published/api/v1.1/items/{asset_id}?channelToken={channel_token}
Upon issuing the
GET200 OK{
"id": "CORE5E4EEA3FB332488589EA08D7D4705999",
"type": "NewsArticle",
"name": "My First News Article",
"description": "",
"slug": "1481786211989-my-first-news-article",
"language": "en-US",
"translatable": true,
"createdDate": {
"value": "2020-03-26T19:15:55.710Z",
"timezone": "UTC"
},
[...]
Note that in the preceding two screenshots, the instance name and cloud account name have been obfuscated and should be replaced with your own details.
Retrieving content through cURL
To retrieve our NewsArticle through the command line, we can use cURL, a command-line tool. The OCE REST API documentation contains information about using cURL to access the Content Management API with useful initial steps for those unfamiliar with cURL.
To test an API call from cURL, issue the following command, where
{instance_name}{cloud_account_name}curl -i -X GET https://{instance_name}-{cloud_account_name}.cec.ocp.oraclecloud.com/content/published/api/v1.1/items/CORE5E4EEA3FB332488589EA08D7D4705999\?channelToken\=99e76da7c5d24c11aa806ac58a46b42aYou will receive a response that returns the JSON from the previous section as seen in the following screenshot (note that the instance name and cloud account name have been obfuscated).
Retrieving content through an XMLHttpRequest
Finally, we can also retrieve our NewsArticle asset from any JavaScript application or in the browser by employing the XMLHttpRequest API.
To test an API call using
XMLHttpRequestXMLHttpRequestsend(){instance_name}{cloud_account_name}var req = new XMLHttpRequest();
req.open("GET", "https://{instance_name}-{cloud_account_name}.cec.ocp.oraclecloud.com/content/published/api/v1.1/items/CORE5E4EEA3FB332488589EA08D7D4705999?channelToken=99e76da7c5d24c11aa806ac58a46b42a");
req.send();You will receive a response that returns the JSON from the previous section. Note that if you are issuing a variety of
GETopen()Conclusion: How to learn more about headless OCE
To learn more about using Oracle Content and Experience as a headless content management system, you can browse the Headless CMS section of the OCE documentation, where you can find information about the Content Delivery and Content Management APIs as well as software development kits (SDKs) that can aid your implementation. In addition, you can download sample OCE sites and learn about the open-source ecosystem surrounding OCE on the OCE middleware downloads page.
As digital experience ecosystems continue to grow at organizations the world over, a headless content management system that also offers rich content and collaboration capabilities is of paramount importance. With features such as API differentiation on a channel basis, Oracle Content and Experience (OCE) is particularly well-positioned as a headless CMS that can accelerate the development of your websites, web applications, mobile applications, and any other conceivable digital experience.
