Learn about the Embed UI API V2

The following topics describe how to embed the Oracle Content and Experience web interface into other applications, using the Embed UI API V2:

Set Up to Use Web UI Embedding Features

Before using the Oracle Content and Experience web UI embedding features, you need to enable embedded content on the Security tab in the System Administration area.

You will also need to include the domain for the application hosting the embedded user interface in the the list of allowed domains.

Note:

Before implementing an interface solution that uses inline frames, be sure you understand the possible security risks associated with hosting external sites in inline frames. Security measures vary between different browsers and different browser versions. For more information, see http://www.w3.org/TR/UISecurity/.

Use the Javascript API

The Oracle Content and Experience embedded API is accessed through a simple Javascript file.

The Javascript file can be obtained and referenced from the Oracle content delivery network (CDN) using an HTML script tag:

<scripttype="text/javascript"src="https://static.oracle.com/cdn/cec/api/oracle-ce-ui-2.1.js"></script>

The Javascript API defines the OracleCEUI namespace, which provides access to the embeddable components. Before any component iframe can be created, the API needs to be initialized with the address of the target Oracle Content and Experience system. This is done by setting the oceUrl property:

OracleCEUI.oceUrl = "https://<service>-<tenant>.cloud.oracle.com"

Once the Oracle Content and Experience system URL is set, you can use the createFrame function for the desired component to create and an iframe DOM object. The createFrame function accepts an options object for customizing the features of the embeddable UI and an events object containing callback functions.

varframeElement = OracleCEUI.assetsView.createFrame(options, events);
document.body.appendChild.(frameElement);

The following topics describe how to use the Javascript API to embed the Oracle Content and Experience web interface into other applications, with the Embed UI API V2:

Authentication and SSO Environments

If you have signed in to the full Oracle Content and Experience web client in another tab, then the embedded web UI will load without additional authentication, using the already established session in the browser.

If there is no existing browser session, then the behavior of the API is to present a sign-in screen in a popup browser window. Once credentials are provided in the popup sign-in window, the embedded web UI will reload without further authentication.

Note:

This behavior requires that any browser popup blockers are configured to allow the popup to display.

When the page hosting the embedded web UI is within the same Oracle Access Manager Domain (Single Sign On), you must call OracleCEUI.ssoInit() before creating any embedded components. In SSO mode, the embedded UI assumes that there is an existing SSO session established in the browser and no popup authentication is required.

The ssoInit function establishes the appropriate session cookies required for access to Oracle Content and Experience. The ssoInit function is an asynchronous call and. therefore, returns a Promise object.

For example:

OracleCEUI.oceUrl = "https://<service>-<tenant>.cloud.oracle.com" 

OracleCEUI.ssoInit().then(function() {
	var frameElement = OracleCEUI.assetsView.createFrame(options, events);
	document.body.appendChild.(frameElement); 
});

Use Oracle Content and Experience REST APIs

The OracleCEUI.ssoInit function is also useful for making REST API calls to Oracle Content and Experience.

As with its use for embedded components in an SSO environment, ssoInit can be used in the same way to establish SSO session cookies before making REST API calls to Oracle Content and Experience. Note that for this to work, the Cross-Origin Resource Sharing (CORS) configuration must be set up properly on the Oracle Content and Experience Administration Security tab to allow requests from the hosting domain.

language js
OracleCEUI.ssoInit().then(function() {
	var xhr = new XMLHttpRequest();
	xhr.onreadystatechange = function(){ if (this.readyState == 4 && this.status == 200) {//do something with xhr.responseText}};
	xhr.open("GET", OracleCEUI.oceUrl + "/content/management/api/v1.1/repositories", true);
	xhr.setRequestHeader("Authorization", "Session");
	xhr.send(); 
});

Options

The options parameter to the createFrame function is a simple Javascript object containing properties for each of the embeddable components. Properties for multiple components can be passed into createFrame at the same time.

For example, when creating an embedded Assets View (assetsView), you can choose to pass both the assetsView property as well as the assetViewer property. This allows for an independent configuration for the Asset Viewer screen if the user chooses to select and open an asset in the embedded Assets View.

For example, the following options will hide the header in the Assets View but display it when the user opens an asset in the Viewer:

language js
var events = {
	selectionChange: function(frame, selection) {
		if (selection.length > 0) {
			OracleCEUI.assetsView.getItem(frame, selection[0].id, {expand: "publishedChannels"}).then(function(item) {
				console.log(item.publishedChannels);
			});
		}
	}
};
var frameElement = OracleCEUI.assetsView.createFrame({}, events);
document.body.appendChild.(frameElement);

OracleCEUI.conversationView.closeService(frameElement).then(function() {
	frameElement.remove();
});

The options parameter is optional. If not provided (or if an empty object is provided), the embedded web UI will default all possible settings. Generally speaking, the default view is a base user interface with most features disabled. You must deliberately opt in to the feature you want presented.

Option settings can be used only to enable a feature that is available in the full web client user interface for a given context. For example, enabling the categories filter panel tab (options.assetsView.filter.tabs.categories = true) will display the tab only if the selected repository is configured with taxonomies.

Use Annotations in the Embedded UI

The header buttons to add and show annotations in the assetViewer, contentItemEditor, and documentViewer components are hidden by default, but they can be displayed by setting the header.annotate option equal to true for each component.

However, annotations rely on the conversation side panel and, therefore, the sidebar.conversation options must be enabled as well. Additionally, annotation functionality is dependent on real-time updates from the conversation to function properly, so converations.enterHive must be enabled as well. As described in Real-Time Updates for Embedded Conversations, whenever enterHive is used, the listening service must be terminated by calling and waiting for conversatonView.closeService to complete.

language js

var options = {
	assetViewer: {
        id: "<id>",
		header: { annotate: true },
		sidebar: { conversation: true }
	},
	conversations: { enterHive: true }
};

var frameElement = OracleCEUI.assetViewer.createFrame(options);
document.body.appendChild.(frameElement);

...

OracleCEUI.conversationView.closeService(frameElement).done(function() {
	frameElement.remove();
});

Dialog Options

In addition to providing settings for the primary, embeddable components, the options object also provides settings for configuring certain dialogs that might appear as a user works with the embedded web user interface.

As with the primary components, most features of a dialog are disabled for the embedded web UI and must be deliberately enabled. Only dialog features that are available in the full user interface for that dialog can be enabled.

Dialog options are available for the following dialogs:

  • Preview (assetPreview)
  • Languages (assetLanguages)
  • Add to Repository (addToRepository)
  • Select File (documentPicker)
  • Select Media (mediaPicker)
  • Select Reference (referencePicker)

For example, the following options will enable the Preview action in the Assets View and disable the Download action when the Preview dialog is opened.

var options = {
    assetsView: {
        actions: {
            preview: true;
        }
    },
    dialogs: {
        assetPreview: {
            actions: {
                download: false;
            }
        }
    }
};

Events

User activity with the embedded web UI will trigger a specific event. You can enable event handler functions for these events by providing them in the the events parameter of the createFrame function.

In following example, the selectionChange event is handled for the embedded Assets View to enable an OK button element. The selection mode is set to single select as well.

var options = {
    assetsView.select = "single";
};
var events = {
    selectionChange: function(frame, selection) {
        document.getElementById("okButton").disabled = (selection.length > 0);
    }
};
var frameElement = OracleCEUI.assetsView.createFrame(options, events);
document.body.appendChild.(frameElement);

Helper Methods

Certain components provide functions to allow programmatic control of certain features of the embedded UI or to obtain additional information.

These helper methods are provided as functions on the component property within the OracleCEUI namespace.

The following example clears any selected items in the Assets View.

 varframeElement = OracleCEUI.assetsView.createFrame(options,events);
 document.body.appendChild.(frameElement);

 OracleCEUI.assetsView.clearSelection(frameElement);

And, the next example obtains more detailed information (specifically, publishedChannels) about a selected item in response to the selectionChanged event.

The assetsView.getItem method is an asynchronous call and, therefore, returns a Promise object. Refer to the getItem reference information that follows for details.

var events = {
    selectionChange: function(frame, selection) {
        if (selection.length > 0) {
            OracleCEUI.assetsView.getItem(frame, selection[0].id, {expand: "publishedChannels"}).done(function(item) {
                console.log(item.publishedChannels);
            });
        }
    }
};
var frameElement = OracleCEUI.assetsView.createFrame({}, events);
document.body.appendChild.(frameElement);

Real-Time Updates for Embedded Conversations

Embedding a conversation view in the web user interface disables back-channel communication with the server by default.

This means the view is a static display of the conversation at the time it was loaded, and the view will not display real-time updates. To get real-time updates, you set the conversations.enterHive option to true when you create any component that might use a conversation view (including sidebars in assets or documents views).

If real-time updates are initialized for an embedded UI, their listening service must be terminated before the iframe containing the embedded UI is destroyed. Terminating this service is an asynchronous operation, and the hosting application must wait for this operation to complete. To close the listening service, you must call the closeService method on either the conversationsList or conversationView component. Calling the closeService method on either component will do the same thing, regardless of which component was used to load the embedded UI.

The conversationView.closeService method is an asynchronous call and therefore returns a Promise object. For details, refer to the conversationView reference information that follows:

var frameElement = OracleCEUI.conversationView.createFrame({id: "18123", enterHive: true});
document.body.appendChild.(frameElement);
  
...
  
OracleCEUI.conversationView.closeService(frameElement).done(function() {
    frameElement.remove();
});

Embed a Folder or File Using a Public Link

You can use a public link generated by Oracle Content and Experience to embed a folder or file using the Documents View and Documents Viewer components, respectively.

Using the link ID from the public link in the options for documentsView and documentViewer circumvents the authentication, displaying the folder or file with the permissions configured by the creator of the public link.

To embed a public link, identify the item ID and link ID in the path segments of the link and pass them as options to the component.

https://<OCE_Instance>/documents/link/<linkId>/folder/<folderId>
https://<OCE_Instance>/documents/link/<linkId>/fileview/<fileId>
var options = {
   documentsView: {
      id: <folderId>,
      linkId: <linkId>
   }
}
varframeElement = OracleCEUI.documentsView.createFrame(options);
document.body.appendChild.(frameElement)

Embed a Folder or File Using an Applink

You can use an Applink resource to display the embeddable Documents View and Document Viewer. The Applink resource encrypts the user and permissions that will be available when the folder or file is embedded.

The Applink is obtained by using the AppLink REST API, which returns a response containing an appLinkID, accessToken, and refreshToken.

To embed the Applink, the appLinkID, accessToken, and refreshToken from the Applink REST API response are passed into the documentsView or documentViewer component as options.

// Get <appLinkID>, <accessToken>, and <refreshToken> from Applink REST API response
 
var options = {
   documentsView: {
      id: <folderId>,
      appLink: {
        appLinkID:"<appLinkID>",
        accessToken:"<accessToken>",
        refreshToken:"<refreshToken>"
      }
   }
}
var frameElement = OracleCEUI.documentsView.createFrame(options);
document.body.appendChild.(frameElement)