5 Connecting to Headless Experiences

Oracle Content Management provides a way to connect content repositories and publishing channels to headless experiences developed and managed outside of Oracle Content Management and automatically trigger deployments based on content changes or published status.

Content providers can leverage the advantages of repository asset management such as powerful tools to organize, retrieve, translate, collaborate on, approve, and publish content. Then, without leaving Oracle Content Management, they can preview, in context and with content, their headless applications.

Experience developers can work with tools they have and configure headless experiences to automatically build based on changes to content in associated repositories or publishing status of content in associated publishing channels, to drive continuous integration/continuous deployment (CI/CD).

The following topics describe how to create and configure connections to experiences outside of Oracle Content Management:

Create an Experience Object

To create an experience object in Oracle Content Management that connects to a headless experience outside of Oracle Content Management, you need to be an enterprise user with the developer role and have a good understanding of the 3rd party application used to create and manage the experience you are connecting to.

Note:

Only one experience object can be created on an Oracle Content Management Starter Edition instance. For unlimited objects, upgrade to Premium Edition.
  1. Click Experiences on the side navigation panel.

  2. On the Experiences page, click Create.

  3. Enter a name, optional description, and default URL of the headless experience you are connecting to, then click Create. The default URL is typically the site URL of the headless experience you're connecting to and is necessary to view the experience in Oracle Content Management.

Note: there are some limitations in the type of information that can be used in each field.

Field Limitation
Name (required)
  • Maximum string length is 256 characters.

  • The string must not contain the chacacters;":?<%>{}/#\|*

Description (optional)
  • Maximum string length is 500 characters.

  • The string may contain any characters.

Experience URL (required to open experience preview)
  • Maximum string length is 4000 characters.

  • The string may contain any characters valid in a URL.

  • The string should parse to be a valid URL.

Configure Experience Object Properties

Once an experience object has been created, you must configure it to include outgoing targets that automate headless experience deployment based on content lifecycle events from Oracle Content Management. When a target is triggered, Oracle Content Management sends a request to the URL endpoint you specify in the outgoing target when you define the target. A URL endpoint is typically implemented in your headless experience to receive and respond to an outgoing target, typically automating a CI/CD workflow. For example, a notification about updated content might initiate a new build of the experience, flush caches, or take any other actions needed for the experience to use the updated content.

  1. On the Experiences page, select the experience object and click Properties in the actions bar.

  2. Under the properties tab, you can review information about the experience object, modify the description or default URL, and enable or disable the headless experience connection. Disabling it prevents content lifecycle events from triggering targets in the experience object.

Up to ten targets per experience can be configured to handle different deployment scenarios based on certain content lifecycle events. For example, one target may be triggered when a new version of an unpublished asset is updated in a repository, initiating a preview of the experience, while a second target may be triggered when an asset is published or republished to a channel, initiating a new build.

The response received back from the endpoint is processed using rules defined in the Analyze tab when configuing the experience object properties. The response could include:

  • the target identifier that was included in the request

  • a status message or code

  • the URL at which the updated headless experience can be viewed

Add Outgoing Targets to Experience Objects

To automate deployment and preview of headless experiences from within Oracle Content Management, you must add targets and specify trigger events on the Outgoing tab of the experience object properties. You can configure up to ten targets to handle different deployment scenarios based on certain content lifecycle events.

  1. With the experience object properties panel open, click the Outgoing tab.

  2. To add an outgoing target, click Add.

  3. Enter a name for the target, the URL endpoint, and specify which method to use, GET or POST.

    Note:

    URL endpoints must use the secure https protocol.
  4. Choose the Oracle Content Management event that triggers the target to deploy and specify the repositories (for asset change events) or channels (for asset published events).

    • Changes—the target is triggered when an asset is changed in a specified repository.

    • Publishes—the target is triggered when an asset is published in a specified publishing channel.

  5. Click Headers and Body to add any additional required information, if necessary.

  6. Click Save.

  7. Click Test to manually trigger the target. Triggering the target sends a request to the target endpoint to solicit a response, typically in the form of a JSON body payload. If the request is valid, you can refresh the events listed on the Events tab to see it listed with additional information. If the request is invalid, an error message is displayed.

Add a TARGET_IDENTIFIER Token

You can add the {{TARGET_IDENTIFIER}} token to an outgoing target. This token will add the target ID to the request when the target is triggered either automatically by content lifecycle events or manually by clicking Test. Where you add the {{TARGET_IDENTIFIER}} token depends on the 3rd party application you use to manage your headless experience. In some cases it may be added to the URL endpoint, to the HTTP body, or HTTP header.

When an incoming payload is received, the payload is evaluated to see if a target ID exists. If a target ID is found that matches an outgoing target ID in an Oracle Content Management experience object, then that payload is associated with the outgoing target that has that ID.

Once a payload is associated with a target, then the event item is logged on the Events tab with the proper title. If the payload is associated to a target and a URL is matched with the URL introspect string configured on the Analyze tab of a target, then that URL is stored as the preview URL for that target.

If a target ID is not found in an incoming payload that matches an outgoing target ID, the payload cannot be associated to a target and it is displayed as Unknown in the Events tab.

Enable and Disable Incoming Webhook

Oracle Content Management makes it easy for your content contributor to view the latest versions of your headless experience. When your headless experience is updated, your deployment system can notify Oracle Content Management by sending a request to the experience webhook. All incoming requests are logged to the Events tab.

You can review the incoming webhook URL and enable or disable it on the Incoming tab of an experience properties panel.

Analyze and Extract Payload Information

The Analyze tab allows you to extract information from an incoming response payload and display it on the Events tab to provide information important to content editors and contributors, such as when their content is saved, published, or goes live.

When a target is triggered and a request is sent to the endpoint URL of your headless experience, the experience returns a response payload. The response payload is combined with the request and the combined data structure is displayed as an event item on the Events tab, with the response payload in an httpBody section of an event item.

On the analyze tab, you can encode the JSON path to the information you want to extract within double-braces {{}} to create an introspect string that extracts the requested data from the httpBody section of a payload. The extracted information is displayed in the event listing on the Events tab.

For example, let's say a section of the payload is as follows:
"httpBody": {
  "data": {
    "url": "https://sample.com",
    "status": "Building",
    "name": "Sample Target"
  }
}

You would specify the JSON paths to the URL, status, and name data on the Analyze tab as the following URL Introspect strings:

{{data.url}}
{{data.status}}
{{data.name}}
Analyze tab

The URL, deployment status, and name of the deployment is then listed dynamically on the Events tab.

Events tab

Note:

The URL introspect string has special status and is reserved for identifying a URL to preview the deployment of the associated target. This URL value is stored and used to preview the latest results of a triggered target when viewing an experience object.

You can also hard-code string values. One reason to do this is to label the JSON path result to easily identify the information for a content contributor. For example, when extracting the name of a deployment, you could enter
Name: {{data.name}}
in an introspect string on the Analyze tab. This would result in Name: Sample Preview being displayed on the Events tab for that target.
Similarly, you can combine encoded JSON paths and hard-coded strings in one instrospect string entry. For example,
Name: {{data.name}} Status: {{data.status}}
would result in Name: Sample Preview Status: Building being displayed on the Events tab for that target while the preview was building.

If there is a spelling or syntax error when encoding a JSON path in an introspect string, the string interpretation will fail and the information will not be extracted from the payload or displayed on the Events tab. If you are using more than one JSON path in an event string, an error in one will cause all to fail.

View Event Information for an Experience

Event information for a headless experience is listed on the Events tab of an experience object properties panel. You can expand an event in the list to see the complete payload and review details about incoming and outgoing notifications useful to a headless experience developer.

The Events tab logs all information contained in a payload. You can refine what information is displayed in the event list in order to provide useful information to content providers by using introspect strings on the Analyze tab. This helps you and the content provider see useful information quickly, such as build status or preview URL, withouth having to expand and review the entire payload to find the information.

View Connected Headless Experiences

Once a headless experience outside of Oracle Content Management is connected, content providers can view headless experience events within Oracle Content Management. This automates their workflow by publishing or building a preview of the headless experience when they trigger an event, either by editing or publishing an asset, depending on how the experience is configured.

To view a headless experience, select the experience object and choose View from the right-click menu or click View icon on the actions bar.

Once the experience panel is displayed, choose the target you want to view from the drop-down list. The headless experience is displayed in an iframe. If the experience cannot be displayed properly in an iframe for security reasons, click Launch to view the experience in a new browser tab.

Launch Properties After a Successful Experience Creation

Users typically need to customize an experience after creating it. Oracle Content Management launches the properties and switches to the Outgoing tab after you complete the create wizard.

Set Security Admin Settings Through APIs

If you have a service administrator role, you can set security admin settings through APIs.

You can also update CORs lists to standardize CORS handling across Docs, Caas, and OSN.

Sharing an Experience Object

If you have created an experience object or are a manager of an experience object that has been shared with you, you can share it with others to allow them to use or edit the object.

Note:

Because experiences are available only to enterprise users, you can share experience objects only with other enterprise users.
  1. Open the Experiences page and select the experience object you want to share.

  2. Select or click Members in the right-click menu or action bar.

  3. Click Add Members in the side panel.

  4. Enter the names or email addresses of the people with whom you want to share the experience object. You can delete or modify the optional message sent to new members.

  5. Select the role you want the added member or members to have. The selected role is assigned to all members that you list in this process. You can go through the process several times if you want to specify different roles for different members, or change the roles individually once they've been added.

    The following roles can be assigned to experience object members.

    • Owner—The owner is the person who created the experience object and cannot be changed. They have full control of the object, object properties, and members.

    • Manager—A manager has full control of the object, object properties, and members.

    • Contributor—A contributor has full control of the object and object properties, can see the list of members, but cannot add or remove members.

    • Viewer—A viewer can see and use an experience object, but cannot change it in any way. They can also see the list of members, but cannot add or remove members.

    • Remove—If you are an owner or manager, you have the option to remove the role assigned to a member, which removes them as a member of the experience object.

  6. When you've finished selecting the people you want to add, click Add. The people you selected are listed as members in the members side panel.

  7. Click Done to close the members side panel.

Filtering Experience Objects on the Experience Page

You can select what experience objects are displayed on your Experiences page by selecting an option from the title menu. The following filter options are available.

  • All—All experience objects created by you or shared with you are listed.

  • Owned by you—Only experience objects created by you are listed.

  • Shared with you—Only experience objects shared with you are listed.