== THIS API HAS BEEN DEPRECATED ==

Embed UI API V1 for Oracle Content Management (DEPRECATED)

Introduction

The Embed UI API V1 for Oracle Content Management enables you to embed the Oracle Content Management web user interface into your own web applications in an HTML inline frame (iframe tag), using parametrized URLs. This API has been deprecated, but will remain available until further notice. Sometime in the future, V1 will no longer be supported. Please use the Embed UI API V2 for any new implementations.

The following topics describe how to embed the Oracle Content Management web interface with Embed JavaScript API V1:

Embed the Web User Interface for Assets

Embed the web user interface for assets into your web applications to access digital assets in an Oracle Content Management asset repository.

The next two figures show both versions of the web user interface. The first figure shows the user’s assets with an asset repository selected in the standard interface.

Screenshot showing the Assets page in the Oracle Content Management web interface.

The following figure shows an example of the same asset selection using the embedded web interface in the Assets View. Note that the banner and side panels are not displayed in the embedded web user interface.

Screenshot showing the Assets page as it appears in embedded form.

To embed the Oracle Content Management web user interface for assets in an inline frame (HTML iframe tag), add /embed immediately before the /assets element in the URL that’s used to populate the inline frame. For example, the following URL calls the default assets landing page:

https://www.example.com/embed/assets

Note: The embedded web user interface adjusts the content to fit within windows as small as 320 pixels wide. Windows smaller than 320 pixels begin to hide content on the right edge of the window.

You can specify configuration parameters on the URL to configure the appearance of the embedded web user interface.

The itemUploaded event occurs whenever a new asset is added to a folder or repository, due to a user’s interaction with the embedded client. The event payload contains the new item data and the container (folder or repository). Only one new item will be included in the event. If multiple items are uploaded, multiple events will occur. The event occurs after the upload is complete.

Embed the Web User Interface for Documents

Embed the Oracle Content Management web user interface for documents into your own web applications to access its folder and document management features.

To embed the Oracle Content Management web user interface for documents in an inline frame, add /embed to any member or public folder link immediately after the /documents element in the URL that’s used to populate the inline frame. For example, the following URL calls the standard user interface for documents and shows the home folder for the current user:

https://www.example.com/documents/home/nameasc

To display the home folder in the embedded web user interface, use the following form of the URL:

https://www.example.com/documents/embed/home/nameasc

To open a specified folder in the embedded web interface, use the folder element in the URL and specify the globally unique identifier (GUID) of the folder. For example, the following link opens the specified folder in the embedded web user interface:

https://www.example.com/documents/embed/folder/1713A5712BE73C37891915A0127B594F/nameasc

Note: The embedded web user interface adjusts the content to fit within windows as small as 320 pixels wide. Windows smaller than 320 pixels begin to hide content on the right edge of the window.

You can also embed member links and public links to folders and specify configuration parameters on the URL to configure the appearance of the embedded web user interface.

Authentication and SSO Environments

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

If there’s no existing browser session, then the behavior of the /embed URL 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 that hosts the embedded web user interface is within the same Oracle access manager domain (single sign-on), the /embed segment of the URL should be replaced with /ssoembed. In single sign-on (SSO) mode, the embedded web user interface assumes that there’s an existing SSO session established in the browser and no popup authentication is required. For example:

https://www.example.com/documents/ssoembed/home/nameasc

Real-Time Updates for Embedded Conversations

Using embedEnterHive enables real-time updates to a conversation from other users who may be posting in the conversation, as well as user presence indicators as displayed in the conversation header such as Active or Idle.

Embedding a conversation view in the web user interface disables back-channel communication with the server by default. This means that 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 must add the parameter embedEnterHive to the URL that’s used to load the embedded view, for example:

https://www.example.com/documents/embed/conversation/12345?embedEnterHive

The embedEnterHive parameter can also be used to display a folder or file view that has a side-by-side conversation in the side bar to get real-time updates on the conversation.

Using embedEnterHive is required in an embedded file view for annotations to function properly, for example:

https://www.example.com/documents/embed/fileview/{fileid}/_file.doc?embedEnterHive

The web user interface can’t accurately detect when the iframe containing it is destroyed. When the embedEnterHive parameter is used, the hosting code must signal the web user interface in the iframe to close the service. This is done through a postMessage call:

iframewindow.postMessage({message: "closeService"}, *);

This ensures the client properly sends an “exit hive” call to the server, discontinuing back-channel communication.

Embed Documents Manager on a Site Page

You can embed documents manager on a site page to provide a view of your home page or files in Oracle Content Management. See Building Sites with Oracle Content Management for further details.

Security for Content in Other Domains

When you embed the Oracle Content Management web user interface, it’s enclosed in an inline frame (iframe). Security policies are enforced to minimize the security risks of hosting external sites in inline frames.

In general, inline frames can host content if the protocol, domain, and port of the inline frame are identical to those for the content that it displays. For example, by default, an inline frame on the page http://www.example.com:12345/home.html can host content only if the content's protocol is also http, the domain is www.example.com and the port is 12345.

An administrator can explicitly identify domains outside of the host domain and allow content from those domains to display in the embedded web user interface.

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

Oracle Content Management displays content for authorized users in the embedded web interface. Supported content includes folders, member links, and views of individual files.

All unsupported content, such as public links and content from unauthorized domains, opens in a new browser tab or window depending on the browser settings.

Embed Content in Other Domains

You can display content from Oracle Content Management within other domains. For example, you might embed the Oracle Content Management web user interface into your own web applications to access folder and document management features inside your application.

To allow users to embed content, enable embedded content and add domains in Oracle Content Management:

  1. Sign in to the Oracle Content Management web application as an administrator.

  2. Open the left navigation menu and click System in the Administration area. If you don’t see this option, you don’t have the required user privileges.

  3. Choose Security from the dropdown menu.

  4. Under Embedded Content, select Enabled.

  5. In the Allowed domains box, enter a list of permitted domains, separated by commas. Domains must be in the form www.example.com.

    • To restrict the domain to a particular port, include the port in the specification. For example, www.example.com:12345.
    • If you want to allow a domain that has multiple sub-domains, you can use the * wildcard character. For example, www.example.* includes the domains www.example.com, www.example.co.uk, and so on.

This image shows the Embedded Content section of the Security administration page in Oracle Content Management.

Browser Configuration Parameters

You can include optional parameters in the URL for a folder or folder link to control some aspects of the browser display. This can be very useful for embedding the web user interface in other applications.

Layout Configuration

You can append the layout configuration parameter (lyt) and a single value to the end of a URL for a folder or folder link using the following format:

{URL}/lyt={value}

For example, the following URL uses a member link to display the associated folder in the embedded web interface with a grid layout:

https://www.example.com/documents/embed/folder/FDB8AC67BE3FCFB4984E1327T0000DEFAULT00000000/_Resources/lyt=grid

Note: You can use the layout parameter with folders and folder links in both the standard and embedded web interfaces.

Possible values for the layout configuration parameter
Value Description
list Displays the folder content in the standard list layout.
grid Displays the folder content in the standard grid layout.

Embed Mode Configuration

You can specify an embed mode configuration as a URL query parameter:

Options of the embed mode configuration apply only when you use embed mode URLs, including applink URLs. You can use the following embedded views:

For example:

/documents/embed/folder/{folderId}?hide=header+actions&show=branding&singlesel

In assets view, you can use the repository configuration parameter to preselect the repository filter value:

https://www.example.com/embed/assets/repository/{repositoryID}

You can add individual options directly as parameters. Combine multiple hide and show options with either a plus sign (+) or comma (,). For example:

hide=header+breadcrumbs+sidebar

The following table lists the options you can use for embed mode configuration.

Parameter Value Description
autoplay   Auto plays video and audio content.
channel <channelId> Preselects the channel filter value. Must be valid for the initially loaded (preselected) repository.
channeloptions

<channelId>+

<channelId>+. . .

 Limits the channel filter control to the provided list.
channeloptions none Hides the channel filter control altogether.
collapsetn   Starts with thumbnails area collapsed.
collection <collectionId> Preselects the collection filter value. Must be valid for the initially loaded (preselected) repository.
collectionoptions

<collectionId>+

<collectionId>+. . .

 Limits the collection filter control to the provided list. The list can contain collections from any repository in the repositoryOptions list. Control will display only collection validation for any selected repository. 
collectionoptions none Hides the collection filter control altogether.
contenttype article+blog+. . . Preselects the listed content type filters for assets view.
contenttypeoptions none Hides the content items section in assets view.
contenttypeoptions article+blog. . . Displays the listed content type filters as available options.
docsonly   Includes only documents in list.
fitoriginal   Starts document at original size.
fitpage   Starts with document fit to page.
fitwidth   Starts with document fit to width.
foldersonly   Includes only folders in list.
hide actions Hides all document actions.
hide add Hides Add action in the assets view header.
hide breadcrumbs Hides breadcrumb area.
hide collections Hides Collections action in the assets view header.
hide copy Hides Copy action.
hide delete Hides Delete action.
hide dnload Hides Download action.
hide favs Hides Favorite actions and view menu.
hide fitpage Hides Fit to Page action in file view.
hide fitwidth Hides Fit to Width action in file view.
hide header Hides content header.
hide move Hides Move action.
hide new Hides Create action in header (new folder).
hide nextprev Hides next and previous controls (file view).
hide pin Hides annotation mode pin.
hide props Hides Properties action.
hide rename Hides Rename action.
hide reserve Hides Reserve action.
hide share Hides Share action.
hide sidebar Hides sidebar.
hide thumbs Hides viewer thumbnail area.
hide toolbar Hides toolbar (folder view).
hide trash Hides Trash View menu.
hide upload Hides action upload.
languageoptions en-US+fr-FR+. . . Limits the language filter control to the provided list.
languageoptions none Hides the language filter control altogether.
launch   Launches documents on view (opens new tab versus inline).
loop   Loops video and audio content.
mute   Mutes video and audio content.
nofocus   Don’t take focus.
noopen   Disables action open for folders in folder view and conversations in conversation list (conversation list becomes multi-select).
novidctls   Hides video controls.
noview   Disables action view for files in folder view.
repository <repositoryId> Preselects the repository filter value in assets view.
repositoryoptions

<repositoryId>+

<repositoryId>+. . .

 Limits the repository filter control to the provided list. Must include the repository parameter value, if provided.
show backbutton Adds a back arrow.
show branding Shows branding header (hidden in embed mode).
simpleDisplay   Simplified select list.
singlesel   Single-select.
status published+approved+rejected+draft+pending Preselects the lists status filters.
statusoptions none Hides the status panel altogether.
statusoptions published+approved+rejected+draft+pending Displays the listed status filters as available options.
type images+video+documents Preselects the listed type filters for assets view.
typeoptions images+video+documents Displays the listed type filters as available options.
typeoptions none Hides the Digital Assets Type section or Type panel in assets view.
wide   Displays wide content area.

Browser Configuration

The embed mode configuration has replaced the legacy browser /cfg settings. Existing /cfg settings are supported in embed mode if no legacy query parameters are specified.

Embed Search Results

In an embedded web user interface for Oracle Content Management, search results are available through an embed URL.

The embed URL format for displaying search results for document and folder types is as follows:

https://{domain-name}/documents/embed/search/{search-string}/documents?hide=titlemenu

The hide=titlemenu option parameter must be passed in the URL to hide the list filter drop-down menu. The search type can’t be filtered in an embed URL.

In an embed URL, you can use the same search string that you can use in a URL that’s not embedded. For information about search strings, see Search Content and Conversations in Collaborating on Documents with Oracle Content Management.

You can use these search types in an embed URL:

For example, the embed URL format for displaying search results within a scoped folder, sorted by last updated, is as follows:

https://{domain-name}/documents/search/{search-string}/folder/lastupdated/{folder_guid}?hide=titlemenu

You can use these sort-by types in an embed:

For example, the format for displaying search results for conversation types, sorted by last updated, is as follows:

https://{domain-name}/documents/embed/search/{search-string}/conversations/lastupdated?hide=titlemenu

Embed Sites Content in Another Domain

You can embed an Oracle Content Management site or a site page into a page served from another domain.

To embed a site or site page into an iframe on an external site page that is served from another domain, set the Embeddable Site property to Yes on the site properties page.

See Embed Content in Other Domains in Administering Oracle Content Management.

Integrate Folder and File Selection

You can access folders and files stored on Oracle Content Management Cloud from your own applications.

Two online tutorials show how to make REST API calls to Oracle Content Management Cloud from a web page using JavaScript. These tutorials are on each provisioned instance at a location similar to this URL:

https://{host_name}:{port}/documents/static/api/{tutorial}

The tutorials document the code and code options, and provide a demonstration of the functionality.

Tutorial Description
FilePickerTutorial.html Provides an interface button and supporting JavaScript code to select one or more folders or files and returns the REST response that includes the selection. This method is useful for working directly with folders and files using the credentials of a provisioned user.
LinkPickerTutorial.html Provides an interface button and supporting JavaScript code to select a file and return the public link to the file. This method is useful for providing public access to a specific file.

Both tutorials include options for using an application link (applink) to access folders and files. An application link provides access to a folder or file for a user with a particular role for a period of time. You can use the application link on subsequent calls that access the associated folder or file without having to establish user credentials with each call. For more information, see Applinks Resources in Integrating and Extending Oracle Content Management.

Configure the File Picker with the SitesSDK.filePicker Method

You can use the SitesSDK.filePicker() method to pass configuration parameters in a URL for the embeddable File Picker user interface.

You can pass a number of browser configuration parameters.

You can specify a configuration parameter with either of two options:

Custom options are enabled in an asset URL or a document URL.

The following example uses the hello-there app:

SitesSDK.filePicker({
   statusoptions: 'published+draft',
   autoplay: true,
   showReset: true,
   hide: 'sidebar',
   docsonly: true,
   singlesel: true,
   'multiSelect': false,
   'supportedFileExtensions': ['jpg', 'png']

This example would generate the following URL for the embedded File Picker:

http://localhost:8080/documents/embed/folder/home/nameasc?scheme=light&thinheader=true&layout=grid&docsonly&noview&wide&singlesel&statusoptions=published+draft&autoplay&hide=sidebar